`. It was removed or converted. | | `unsupported_tag` | You sent a tag that `v2` doesn't know. It was saved as literal text. | Log these warnings while you migrate. A `deprecated_tag` warning means your generator still writes `v1` syntax. See [Update warnings](https://developers.notion.com/guides/data-apis/working-with-markdown-content.md#update-warnings) for the response shape. **Meeting note transcripts use a new tag.** `v2` puts the transcript in `` inside ``. See [Transcripts in v2](https://developers.notion.com/guides/data-apis/working-with-markdown-content.md#transcripts-in-v2). ## 5. Test the switch 1. Pick a page that uses the block types your integration reads or writes. 2. Retrieve it twice, once with `markdown_version=v1` and once with `markdown_version=v2`. Diff the two outputs and check each difference against the table below. 3. Run your parser on the `v2` output and confirm it finds the same blocks it found in the `v1` output. 4. On a test page, write your generator's output with `PATCH /v1/pages/:page_id/markdown`, `"type": "replace_content"`, and `"markdown_version": "v2"`. Check that the response has no `warnings`. Then retrieve the page with `markdown_version=v2` and run your parser on it. Check that it finds the blocks you meant to write. Don't compare exact text, because `v2` output can differ from valid input, such as `` for `**`. ## Syntax differences Each row shows the same content in both versions, taken from real API output. Syntax not listed here, such as plain headings, bulleted and numbered list items, `- [ ]` to-dos, links, images, dividers, fenced code, block equations, citations, and custom emoji, is the same in both versions. ### Structure | Content | `v1` | `v2` | Notes | | - | - | - | - | | Between blocks | One newline | One blank line | In `v2`, lines separated by a single newline join into one block. | | Line break inside a block | `
` | `
` | `v2` also accepts a trailing `\` at the end of the line. | | Children of a block | Indented one tab under the parent | Inside the parent's tag, after a blank line, not indented | Nested list items are indented with spaces in `v2` output: 2 under `-`, 3 under `1.`. Tabs still work for list items. | | Block color | `{color="blue"}` at the end of the first line | `color="blue"` on the block's tag | Applies to every block that has a color. | | Empty block | `` | `
` | | ### Blocks | Block | `v1` | `v2` | Notes | | - | - | - | - | | Paragraph with color | `Text {color="gray_bg"}` | `
` `Text` `
` | | | Heading with color | `# Heading {color="blue"}` | `
` `Heading` `
` | Same for `
` to `
`. | | Toggle heading | `## Title {toggle="true"}` with tab-indented children | `` `Title` `Children` `` | | | Toggle | `
` `
Title
` `Children` `
` | `` `Title` `Children` `` | The title is the first line, then a blank line. | | Quote | `> Text` | `> Text` | Same for a plain quote. In `v2`, separate two quotes with a blank line, or they join into one. | | Quote with color or children | `> Text {color="purple_bg"}` with tab-indented children | `` `Text` `Children` `` | | | Callout | `` with tab-indented content | `` `Text` `Children` `` | Same tag. Content isn't indented, and a blank line follows the first line. | | Bulleted list item with color | `- Item {color="blue"}` | `
` `
` `Item` `
` `
` | Use `
` for numbered items. | | To-do with color | `- [ ] Task {color="green"}` | `` `Task` `` | | | Code language | Full name, like ` ```python ` or ` ```typescript ` | Short name, like ` ```py ` or ` ```ts ` | Plain text becomes `txt`. Some names don't change, like `javascript`, `bash`, and `mermaid`. `v2` input accepts the full names too. | | Plain table | `` with `` and `
` | GFM pipe table: `\| Name \| Owner \|` `\| --- \| --- \|` `\| Spec \| Ada \|` | The `\| --- \|` row is required. | | Styled table | `` with one cell per line, like `` | `
Name
` with each cell's content on its own line inside `
` | Used when a table has a header column, colors, or widths. | | File, PDF, video, audio | `Caption` | `` `Caption` `` | `src` becomes `source`. Without a caption, `v2` uses a self-closing tag, like ``. | | Bookmark | `` | `` | `v1` doesn't render bookmarks. | | Embed | `` | `` | | | Table of contents | `` | `` | Underscore becomes hyphen. | | Synced block | `` and `` | `` and `` | Content isn't indented in `v2`. | | Columns and tabs | `` / `` and `` / `` with tab-indented content | Same tags, content not indented | | | Child page | `Title` | `` `Title` `` | | | Child database | `Title` | `` `Title` `` | | | Meeting notes | `` with `
`, ``, and `` | `` with ``, ``, and `` | | ### Inline content | Content | `v1` | `v2` | Notes | | - | - | - | - | | Bold, italic, strikethrough | `**text**`, `*text*`, `~~text~~` | `text`, `text`, `~~text~~` | `v2` output always uses tags. `v2` input accepts both forms. | | Underline | `text` | `text` | | | Inline code | `` `code` `` | `code` | `v2` output uses the tag. `v2` input accepts backticks. | | Inline math | ``$`E=mc^2`$`` | `$E=mc^2$` | | | Escaped `<` and `>` | `\` | `\` | `v2` escapes only `<`. | | User mention | `` | `` | All mentions use one `` tag in `v2`. | | Page mention | `Title` | `Title` | | | Database mention | `Name` | `Name` | | | Data source mention | `Name` | `Name` | | | Agent mention | `Name` | `Name` | | | Date mention | `` | `` | The tag is ``, and attribute names use hyphens. | ## Common problems **Content runs together into one block.** Your generator puts one newline between blocks. Add a blank line between blocks. **A quote swallows the lines after it.** A line right after a `>` line joins the quote. Add a blank line after the quote. **Indented text joins its parent paragraph.** Tab indentation only nests list items in `v2`. For other children, use the parent's tag form, such as `
` or ``. **`{color="..."}` shows up as text on the page.** `v2` doesn't read the `v1` color syntax and doesn't warn about it. Move the color into the block's `color` attribute. **An update fails with `Markdown errors blocked parsing`.** The input mixes syntax that `v2` can't parse, such as an image inside a line of text. The error message says what to fix.