> ## Documentation Index > Fetch the complete documentation index at: https://docs.mark2notion.com/llms.txt > Use this file to discover all available pages before exploring further. # Convert Markdown > Convert Markdown text to Notion block objects ## Overview The convert endpoint transforms Markdown text into Notion block objects that can be used with the Notion API, our append endpoint, or the append-blocks endpoint when you need to append prebuilt blocks. Our converter supports a comprehensive set of Markdown features including GitHub Flavored Markdown (GFM) alerts, advanced formatting, and intelligent text splitting. ## Supported Markdown Features ### Basic Elements * **Headings**: `#`, `##`, `###`, `####`, `#####`, `######` (H4-H6 map to `heading_3`) * **Paragraphs**: Regular text and line breaks * **Text Formatting**: `**bold**`, `*italic*`, `` `code` ``, `~~strikethrough~~` * **Colors**: `colored text` (supports 9 Notion colors) * **Links**: `[text](url)` and `` autolinks * **Images**: `![alt text](image-url)` ### Lists * **Bulleted Lists**: `- item` or `* item` * **Numbered Lists**: `1. item` * **Nested Lists**: Unlimited nesting depth supported * **Mixed Lists**: Combine bulleted and numbered at different levels ### Code * **Inline Code**: `` `code` `` * **Code Blocks**: ` ```language` with syntax highlighting * **Indented Code**: 4+ space indentation ### Advanced Features * **Tables**: Full Markdown table support with headers * **Blockquotes**: `> quoted text` * **GFM Alerts**: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` * **Horizontal Rules**: `---`, `***`, or `___` * **Toggle Blocks**: HTML `
` and `` tags for collapsible sections ### HTML Color Support Add colors to your text using standard HTML syntax: ```markdown theme={null} This is red text and blue text. ``` **Supported Colors:** * `red`, `blue`, `green`, `yellow`, `orange`, `purple`, `pink`, `gray` (or `grey`), `brown` **Features:** * Works with all block types (headings, lists, quotes, etc.) * Can be combined with other formatting (bold, italic, etc.) * Unsupported colors are silently ignored **Examples:** ```markdown theme={null} # Heading with purple text Paragraph with **bold red** text. - List item with green text ``` ### Toggle Blocks (Collapsible Sections) Create collapsible toggle blocks using HTML `
` and `` tags: ```markdown theme={null}
Click to expand Content inside the toggle block can include: - Headings - Lists - Paragraphs - Any other Markdown elements
``` **Features:** * Summary text supports **bold** (`` or ``) and *italic* (`` or ``) formatting * Content can include any Markdown elements (headings, lists, code blocks, etc.) * Nested details blocks are not supported * Malformed HTML is silently ignored **Examples:** ```markdown theme={null}
Email Summary ## Section 1 Title - Bullet point 1 - Bullet point 2 ## Section 2 Title - Another bullet point
``` ```markdown theme={null}
Optional Settings Configure advanced options here.
``` ### Generated Notion Block Types | Markdown Element | Notion Block Type | Notes | | ---------------- | ------------------------------------- | ---------------------------------- | | `# Heading` | `heading_1`, `heading_2`, `heading_3` | H4-H6 map to heading\_3 | | `Text` | `paragraph` | With rich text formatting | | `- Item` | `bulleted_list_item` | Unlimited nesting | | `1. Item` | `numbered_list_item` | Unlimited nesting | | ` ```code``` ` | `code` | With language support | | `> Quote` | `quote` | Standard blockquotes | | `> [!NOTE]` | `callout` | With icons and colors | | `![alt](url)` | `image` | External images | | `\| Table \|` | `table` | With headers | | `---` | `divider` | Horizontal rules | | `
` | `toggle` | Collapsible sections with children | ## Text Length Handling ### Automatic Text Splitting Content longer than 2000 characters is automatically split across multiple `rich_text` objects within the same block: * ✅ **No content loss**: All text is preserved * ✅ **Smart splitting**: Breaks at safe boundaries when possible * ✅ **Maintains formatting**: Bold, italic, and other formatting preserved across splits * ✅ **Transparent**: The splitting is handled automatically ### Example: Long Content ```json theme={null} { "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "First 2000 characters of content..." } }, { "type": "text", "text": { "content": "...remaining characters continue here" } } ] } } ``` ## Request Your Mark2Notion API key The Markdown content to convert to Notion blocks ## Response Will be "success" for successful requests Array of Notion block objects ready for use with Notion API Total number of blocks generated ## Examples ````bash curl theme={null} curl -X POST "https://api.mark2notion.com/api/convert" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "markdown": "# My Heading\n\nThis is a **bold** paragraph with a [link](https://example.com).\n\n> [!NOTE]\n> This is a GitHub-flavored alert that becomes a callout!\n\n- List item 1\n- List item 2\n\n---\n\n## Code Example\n\n```javascript\nconsole.log(\"Hello World!\");\n```" }' ```` ```javascript JavaScript theme={null} const response = await fetch('https://api.mark2notion.com/api/convert', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': 'YOUR_API_KEY' }, body: JSON.stringify({ markdown: `# My Heading This is a **bold** paragraph with a [link](https://example.com). > [!NOTE] > This is a GitHub-flavored alert that becomes a callout! - List item 1 - List item 2 --- ## Code Example \`\`\`javascript console.log("Hello World!"); \`\`\`` }) }); const data = await response.json(); console.log(data.data.blocks); ``` ````python Python theme={null} import requests response = requests.post( 'https://api.mark2notion.com/api/convert', headers={ 'Content-Type': 'application/json', 'x-api-key': 'YOUR_API_KEY' }, json={ 'markdown': '''# My Heading This is a **bold** paragraph with a [link](https://example.com). > [!NOTE] > This is a GitHub-flavored alert that becomes a callout! - List item 1 - List item 2 --- ## Code Example ```javascript console.log("Hello World!"); ```''' } ) data = response.json() print(data['data']['blocks']) ```` ```json Example Response theme={null} { "status": "success", "data": { "blocks": [ { "type": "heading_1", "heading_1": { "rich_text": [ { "type": "text", "text": { "content": "My Heading" } } ] } }, { "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "This is a " } }, { "type": "text", "text": { "content": "bold" }, "annotations": { "bold": true } }, { "type": "text", "text": { "content": " paragraph with a " } }, { "type": "text", "text": { "content": "link", "link": { "url": "https://example.com" } } }, { "type": "text", "text": { "content": "." } } ] } }, { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [ { "type": "text", "text": { "content": "List item 1" } } ] } }, { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [ { "type": "text", "text": { "content": "List item 2" } } ] } } ], "blockCount": 4 } } ``` ## Error Responses Understand error responses and how to handle them. ## Usage Notes Each convert request counts as 1 API call against your quota, regardless of the markdown size. The returned blocks are standard Notion API block objects and can be used directly with the Notion API. The convert endpoint returns raw Notion blocks without additional processing. For content that will be sent to Notion, consider using the `/append` endpoint for Markdown sources or `/append-blocks` when you already have block JSON. Both include smart processing for large payloads, text splitting, and validation.