Markdown to Notion

What Is Notion Block JSON?

The Notion API does not accept Markdown. Content is built from blocks, and every block is a JSON object with a type, an array of rich text fragments, and its own properties. A heading, a to-do item, and a code block are three different block types with three different payload shapes. Writing that JSON by hand is slow and easy to get wrong, especially when a paragraph mixes bold text, inline code, and links.

This converter takes Markdown and produces that block JSON for you. Paste Markdown on the left and the tool maps every element to the matching Notion block in real time, showing the block count as you go.

How to Use It

1. Paste or type Markdown into the input panel. The converter supports headings, paragraphs, lists, task lists, quotes, code fences, tables, dividers, and images.
2. Watch the JSON panel update as you type. Inline formatting becomes rich text annotations instead of literal asterisks and backticks.
3. Choose the output format. The block array is the raw list of blocks, while the children payload wraps it in a {"children": [...]} object that matches the append block children request body.
4. Copy the JSON or download it as a file, then send it to the Notion API from your integration.

Supported Markdown Syntax

• Headings: levels one through three map to heading_1, heading_2, and heading_3. Deeper headings are clamped to level three because Notion only supports three heading levels.
• Inline formatting: bold, italic, strikethrough, inline code, and links become rich text annotations with the correct annotations flags and href values.
• Lists: bulleted and numbered lists map to bulleted_list_item and numbered_list_item, and nested lists are emitted as child blocks.
• Task lists: - [x] and - [ ] map to to_do blocks with the checked state preserved.
• Code fences: the fenced language is normalized to a value Notion accepts, falling back to plain text for unknown languages.
• Quotes and dividers: blockquotes map to quote blocks and horizontal rules map to divider blocks.
• Tables: GitHub style tables map to a table block with a header row and table_row children.
• Images: a standalone image becomes an image block that references the external URL.

Raw HTML inside Markdown is kept as paragraph text so nothing silently disappears. If you need to clean up HTML before converting, the HTML to Markdown tool handles the other direction.

Sending the JSON to the Notion API

The append block children endpoint accepts a body shaped like {"children": [ ...blocks ]}. Select the children payload format in the tool and the wrapper is included for you. Each request can contain up to 100 blocks, so split larger documents into batches. The integration also needs write access to the target page, which you grant when you share the page with your integration from the Notion interface.

One important detail: the API requires every rich text fragment to contain content without newline characters. Line breaks are represented as separate text objects, and this converter handles that automatically, which is exactly the kind of edge case that makes hand written JSON painful.

Why Convert in the Browser

Everything runs locally using the Marked parser, so your draft content is never uploaded. That matters when the Markdown contains internal documentation, customer data examples, or unreleased announcements that you are preparing to publish in a workspace.

Related Tools

If you need standard HTML instead of Notion blocks, use Markdown to HTML. To write and preview Markdown with a live rendered view first, try the Live Markdown Editor. The JSON Formatter can validate and pretty print the generated JSON, and the Markdown Table Generator helps you build the table syntax this converter turns into Notion table blocks.