Markdown to Notion Converter

How This Markdown to Notion Converter Works

This tool parses your Markdown into an intermediate block tree, then maps every node onto the exact JSON shape the Notion API expects — entirely in your browser, with no server round-trip. The same parse also powers the live preview, so what you see on the left is what gets converted on the right.

What is Markdown?

Markdown is a lightweight plain-text formatting syntax — headings with #, lists with -, bold with ** — designed to be readable as-is and easy to convert into richer formats. It's the default authoring format for READMEs, technical documentation, and wikis.

What is Notion?

Notion is a workspace and documentation tool built around a block-based content model: every piece of content — a paragraph, a heading, a to-do item, a table row — is its own structured block object, not a flat stream of formatted text. Notion's public API lets you create and update pages by sending exactly that block structure as JSON.

What Are Notion Blocks?

A Notion block is a JSON object with an object field (always "block"), a type field naming the block kind (paragraph, heading_1, to_do, and so on), and a type-specific object holding that block's content — most commonly a rich_text array. Blocks that can contain other blocks (lists, quotes, callouts, toggles, tables) nest them in a children array inside that same type-specific object.

Markdown vs. Notion: The Core Difference

Markdown describes formatting inline, as characters within a text stream. Notion describes structure explicitly, as a tree of typed objects. Converting between them means turning implicit formatting markers (**bold**) into explicit annotation objects, and turning implicit nesting (indentation) into explicit children arrays — that structural translation is the entire job of this converter.

How the Converter Works

Parsing happens in two passes: first, Markdown is split into block-level elements (headings, paragraphs, lists, tables, code fences, blockquotes) using a line-based scanner; then, each block's inline text is parsed a second time into "runs" — spans of text with bold/italic/strikethrough/code/link/equation flags attached. Runs become Notion rich text objects, and blocks become Notion block objects.

Rich Text Objects

Every piece of readable text in the Notion API is an array of rich text objects, each with a type (usually text or equation), the content itself, an annotations object (bold, italic, strikethrough, underline, code, color), and an optional href for links. A single Markdown sentence with mixed formatting becomes multiple rich text objects concatenated together.

// "Some **bold** text" becomes:
[
  { "type": "text", "text": { "content": "Some " }, "annotations": { "bold": false, ... } },
  { "type": "text", "text": { "content": "bold" }, "annotations": { "bold": true, ... } },
  { "type": "text", "text": { "content": " text" }, "annotations": { "bold": false, ... } }
]

Block Objects & Nested Blocks

Blocks that can contain other blocks — quote, callout, toggle, bulleted_list_item, numbered_list_item, to_do, and table — carry a children array inside their own type object (for example callout.children, not a top-level block.children). A nested Markdown list under a list item becomes exactly that: child list-item blocks nested inside the parent's children array, at any depth.

Lists & Checklists

Unordered list items (-, *, +) become bulleted_list_item blocks, ordered items (1.) become numbered_list_item blocks, and GitHub-style task items (- [ ] / - [x]) become to_do blocks with a boolean checked property — Notion has no separate "checklist" container, a to-do list is simply consecutive to_do blocks.

Tables

A Markdown table becomes a table block whose children array holds one table_row block per row (including the header row), with table_width set to the column count and has_column_header set to true — matching the exact shape the Notion API requires when creating a table.

Callouts (via GitHub Alert Syntax)

Markdown has no native callout syntax, so this converter recognizes GitHub's blockquote-based alert convention — > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] — and maps each to a Notion callout block with a matching emoji icon and background color, which is the same convention many GitHub-to-Notion migration scripts already rely on.

Code Blocks

Fenced code blocks (```js ... ```) become Notion code blocks, with the fence's language tag normalized to one of Notion's recognized language identifiers where possible (js → javascript, py → python, sh → shell). Because Notion caps each rich text segment at 2,000 characters, long code is automatically split across multiple text objects so nothing gets silently truncated.

Equations

Inline LaTeX ($E=mc^2$) becomes an equation-type rich text object inside a paragraph's rich text array; block-level LaTeX ($$ ... $$) becomes a standalone Notion equation block.

Toggle Blocks

Notion's collapsible toggle has no standard Markdown syntax, so this converter recognizes the common <details><summary>Title</summary>...</details> HTML idiom — widely supported by GitHub, GitLab, and most Markdown renderers — and converts it into a Notion toggle block with the summary text as the title and everything else as nested children.

Embeds, Bookmarks & Videos

A line containing nothing but a bare URL is converted to a Notion bookmark block, or a video block automatically when the URL points to YouTube or Vimeo — a lightweight way to carry over reference links from a Markdown doc without losing them.

API Integration

The generated array is ready to drop into the children field of a Notion API Create a page or Append block children request, alongside your integration token and a parent page or database ID that your integration has been shared with.

// Node.js — send the generated blocks to Notion
const res = await fetch('https://api.notion.com/v1/blocks/' + parentBlockId + '/children', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer ' + process.env.NOTION_TOKEN,
    'Notion-Version': '2022-06-28',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ children: generatedBlocks }),
});

Documentation Automation & Knowledge Base Workflows

Teams that write documentation in Markdown (READMEs, ADRs, runbooks) but collaborate in Notion often end up manually re-typing or copy-pasting content, which drifts out of sync. Generating Block JSON here — then scripting the Notion API call — turns that into a repeatable sync step: edit the Markdown source, regenerate, push.

DevOps Documentation & Engineering Wikis

Runbooks, incident postmortems, and API references frequently live in a Git repository as Markdown so they're versioned alongside code. Converting them to Notion Block JSON as part of a CI step keeps an internal engineering wiki current without a human manually reformatting every update.

Common Conversion Issues & Best Practices

• Inline images — Notion's rich text objects don't support an image embedded mid-sentence; only a paragraph containing just an image becomes an image block. Keep images on their own line for a clean conversion.
• Footnotes — Notion has no footnote block type, so footnote references and definitions are preserved as literal paragraph text rather than silently dropped, and flagged in the warnings panel.
• Deep heading levels — Notion supports only heading_1 through heading_3; Markdown headings deeper than ### are generated as heading_3.
• 2,000-character rich text limit — the Notion API rejects a single rich text segment longer than 2,000 characters; this converter chunks long code blocks and paragraphs automatically so a single API call won't be rejected.
• Test against a real integration first — always send a small sample through your actual Notion integration before running a large document through production automation.

Enterprise Use Cases

Beyond individual docs, this same block-mapping logic is useful for migrating an entire GitHub Wiki or Docusaurus site into Notion page-by-page, generating meeting notes templates from a Markdown skeleton, or building an internal "Markdown-in, Notion-out" publishing pipeline for a content or support team.

Privacy & Security

Parsing and block generation run entirely inside your browser's JavaScript engine. No Markdown or generated JSON is ever transmitted to ToolAdda's servers, which makes this safe to use even with private documentation, internal runbooks, or content containing credentials-adjacent context (though secrets should never be committed to Markdown in the first place).

Markdown vs. Notion Blocks

Markdown vs. HTML

GitHub Markdown vs. Notion Markdown

ToolAdda vs. Other Conversion Tools

Related Developer Tools