GFM → Notion blocks · heading_1/2/3 · code · quote · list · paragraph

Convert Markdown to Notion blocks

Reformat Markdown into the Notion block-object JSON the official API accepts — headings, code, quotes, lists, paragraphs and dividers, all mapped in one pass.

Markdown → Notion
Input
220 B
15 lines
Output
1.9 KB
115 lines
Status
ready
live
Ratio
8.95×
out/in
input · markdown
output · notion blocks
[
  {
    "object": "block",
    "type": "heading_1",
    "heading_1": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Release notes"
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "paragraph",
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "**v2.0** ships with _major_ improvements."
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "heading_2",
    "heading_2": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Highlights"
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "bulleted_list_item",
    "bulleted_list_item": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "New `api/v2` endpoint"
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "bulleted_list_item",
    "bulleted_list_item": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Faster startup time"
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "bulleted_list_item",
    "bulleted_list_item": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "See [docs](https://example.com/docs)"
          }
        }
      ]
    }
  },
  {
    "object": "block",
    "type": "code",
    "code": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "console.log(\"hi\");"
          }
        }
      ],
      "language": "js"
    }
  },
  {
    "object": "block",
    "type": "quote",
    "quote": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Watch out: breaking change."
          }
        }
      ]
    }
  }
]
Quick Start

How to convert Markdown for Notion

Notion stores pages as an array of block objects, not as Markdown text. This converter emits the exact JSON shape the Notion API accepts as the children field of a page or block.

  1. 01

    Paste Markdown

    From a README, PR description, or notes — everything stays in your browser.

    Parsing runs through marked with GFM extensions enabled — tables, task lists, strikethrough, and fenced code blocks all match GitHub’s rendering.

    inputGFMmarkedCommonMarklive
    input · markdownmd · GFM
    # Heading
    loaded · GFMGFM · ready
  2. 02

    Map blocks

    # / ## / ### → heading_1/2/3; lists → bulleted_list_item / numbered_list_item; > → quote.

    Soft-break behaviour is configurable: by default a single newline becomes a space (CommonMark), toggle on for chat-style <br> insertion.

    blocksoft-breaksoptionsconfiglive
    fix · optionsblocks · live
    heading_1
    options applied · livelive
  3. 03

    Preserve code + quotes

    ```js → code block with language hint; > text → quote block; --- → divider.

    The preview is scoped under a .mde class so its CSS doesn’t bleed into the rest of the page. Output HTML is whitespace-controlled for clean diffs.

    macropreviewscoped CSSrenderstable
    out · renderedjson · ready
    { "type": "code" }
    rendered · liverendered
  4. 04

    POST to Notion

    Use the JSON as the children array on a PATCH /v1/blocks/{id}/children or a new page payload.

    Export covers both raw Markdown and rendered HTML; downloads stream as text/markdown or text/html via Blob + object URL.

    exportclipboard.md.htmlblob
    ✓ · exportednotion · done
    ✓ posted
    shipped · ready to shipsuccess
Pro tips

Author Markdown that renders everywhere

GFM is the safe default

GitHub-Flavored Markdown is the de-facto baseline (tables, task lists, strikethrough). CommonMark is stricter but ubiquitous as a fallback.

Soft-break behaviour varies

A single newline is a space in CommonMark, a <br> in GFM. Toggle soft breaks when source matters.

Escape inside code fences

Backticks inside fenced blocks need a longer fence — three becomes four. Use ~~~ if your content has many backticks.

Anchors are slugified

GitHub lowercases, strips punctuation, and joins with hyphens. Duplicate headings get -1, -2 suffixes.

Tables need a header row

The dash row sets alignment (:---, :-:, ---:). Use Table Aligner for diff-friendly columns.

Front matter is YAML

Triple-dash blocks at the top of files are parsed by static-site generators. Use the Front-Matter Validator to catch syntax errors.

Use Cases

When to convert for Notion

Sync engineering content from Git into a Notion workspace.

Sync docs

Mirror Markdown READMEs into engineering Notion pages. Render path uses marked with GFM extensions enabled (tables, task lists, strikethrough, autolinks), so what you preview matches what GitHub publishes bit-for-bit. Soft-break behaviour is configurable for chat-style vs prose Markdown.

GFM-compliant

Release notes

Push GitHub release notes into a Notion changelog DB. Pairs cleanly with the Markdown Cheatsheet for syntax you can't quite remember — callout blocks, footnotes, definition lists. Output stays diff-friendly so style-only changes don't drown out real edits in PRs.

GitHub-perfect

RFC publication

Promote a Markdown RFC into the Notion design space. Cross-platform safe: anchors, code fences, and tables behave identically on GitHub, GitLab, Bitbucket, and Gitea. Heading-anchor slugs follow GitHub's lowercase-and-hyphenate rules so deep links survive a docs migration.

diff-friendly

Knowledge base

Bulk-migrate legacy Markdown wikis into Notion. No server roundtrip — perfect for proprietary content you can't paste into a public tool. The full marked + GFM bundle ships with the page, so it works offline once loaded.

render-stable

Standups

Push daily Markdown notes into a Notion log. Front matter (YAML / TOML / JSON) passes through unchanged so static-site pipelines (Jekyll, Hugo, Astro, Eleventy) read it correctly. Pair with the Front-Matter Validator to catch syntax errors before deploy.

cross-platform

API automation

Pre-shape payloads for Notion API integrations. Output is reproducible: identical input always produces identical Markdown, so doc-generation scripts can rely on it for snapshot tests and embedded into release workflows.

SEO-friendly
FAQ

Frequently asked questions

No. The converter only emits the JSON shape the Notion API expects (the children array of block objects). It never talks to Notion — you take the output and use it however you like.
GFM-style ATX headings (H1–H3 map to Notion heading blocks), unordered and numbered lists, fenced code blocks with language hints, blockquotes, horizontal rules, and paragraphs. Inline bold / italic / links are preserved as plain text inside paragraphs.
Notion supports only three heading levels (H1, H2, H3). H4 and deeper are emitted as paragraph blocks — the closest visual equivalent that survives a Notion paste.
Yes — use it as the children parameter when calling POST /v1/pages (to create a new page) or PATCH /v1/blocks/{id}/children (to append to an existing page) via the Notion REST API.
No. Everything runs locally in your browser. Internal docs, customer data, draft posts — they all stay on your machine.
Suggest a tool

Something missing?

Tell us what you need. We ship the top requests every two weeks.

Sent straight to the maintainers · no account needed
47 in queue·8 shipped this month
Request queued. Thanks!