[{"data":1,"prerenderedAt":70},["Reactive",2],{"blog-post-markdown-for-notion-what-actually-works":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":40,"related":43},"markdown-for-notion-what-actually-works","Markdown for Notion: What Actually Works and What Doesn't","A practical guide to importing, writing, and exporting Markdown in Notion — what converts cleanly, what breaks, and reliable workarounds for each case.","Notion markets itself as Markdown-friendly, and for basic formatting it mostly is. But spend enough time moving documents between Notion and the rest of your toolchain and you'll hit the edge…","2026-06-26","workflows","Matt Rathbone","markdown notion, notion markdown import, notion markdown export, notion markdown support, paste markdown notion, notion markdown rendering",6,"\u003Cp>Notion markets itself as Markdown-friendly, and for basic formatting it mostly is. But spend enough time moving documents between Notion and the rest of your toolchain and you'll hit the edge cases: frontmatter that renders as prose, tables that become databases, Mermaid diagrams that become plain text, and HTML that disappears entirely.\u003C/p>\n\u003Cp>This is a guide to what actually happens — not what the docs say should happen.\u003C/p>\n\u003Ch2 id=\"how-notion-handles-markdown-input\">How Notion Handles Markdown Input\u003C/h2>\n\u003Cp>Notion has three different ways to get Markdown in, and they don't all behave the same:\u003C/p>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Method\u003C/th>\n\u003Cth>Best for\u003C/th>\n\u003Cth>Reliability\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Cstrong>Paste\u003C/strong>\u003C/td>\n\u003Ctd>Short snippets, quick formatting\u003C/td>\n\u003Ctd>Medium — tables and code blocks often break\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>File import\u003C/strong> (drag .md file)\u003C/td>\n\u003Ctd>Full documents, preserved structure\u003C/td>\n\u003Ctd>High — most reliable option\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>\u003Ccode>/markdown\u003C/code> slash command\u003C/strong>\u003C/td>\n\u003Ctd>Pasting a block of Markdown text\u003C/td>\n\u003Ctd>Medium — same caveats as paste\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Cp>\u003Cstrong>File import is more reliable than paste.\u003C/strong> When you paste Markdown, Notion processes it in real time, which can produce odd results with complex tables and fenced code blocks. Dragging a \u003Ccode>.md\u003C/code> file into the sidebar triggers Notion's dedicated importer, which handles the format more consistently.\u003C/p>\n\u003Ch2 id=\"what-converts-cleanly\">What Converts Cleanly\u003C/h2>\n\u003Cp>These elements survive the trip from Markdown to Notion reliably:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Headings\u003C/strong> (\u003Ccode>#\u003C/code>, \u003Ccode>##\u003C/code>, \u003Ccode>###\u003C/code>) → Notion heading blocks (H1, H2, H3)\u003C/li>\n\u003Cli>\u003Cstrong>Bold and italic\u003C/strong> (\u003Ccode>**bold**\u003C/code>, \u003Ccode>*italic*\u003C/code>) → rich text formatting\u003C/li>\n\u003Cli>\u003Cstrong>Inline code\u003C/strong> (\u003Ccode>`code`\u003C/code>) → inline code formatting\u003C/li>\n\u003Cli>\u003Cstrong>Fenced code blocks\u003C/strong> with language labels → Notion code blocks with syntax highlighting\u003C/li>\n\u003Cli>\u003Cstrong>Unordered lists\u003C/strong> (\u003Ccode>-\u003C/code>, \u003Ccode>*\u003C/code>) → bulleted list blocks\u003C/li>\n\u003Cli>\u003Cstrong>Ordered lists\u003C/strong> (\u003Ccode>1.\u003C/code>, \u003Ccode>2.\u003C/code>) → numbered list blocks\u003C/li>\n\u003Cli>\u003Cstrong>Checkboxes\u003C/strong> (\u003Ccode>- [ ]\u003C/code>, \u003Ccode>- [x]\u003C/code>) → to-do blocks\u003C/li>\n\u003Cli>\u003Cstrong>Links\u003C/strong> (\u003Ccode>[text](url)\u003C/code>) → hyperlinks\u003C/li>\n\u003Cli>\u003Cstrong>Blockquotes\u003C/strong> (\u003Ccode>>\u003C/code>) → Notion quote blocks\u003C/li>\n\u003Cli>\u003Cstrong>Horizontal rules\u003C/strong> (\u003Ccode>---\u003C/code>) → divider blocks\u003C/li>\n\u003C/ul>\n\u003Cp>For plain prose documents, Notion is actually solid. The problems start with the more complex elements.\u003C/p>\n\u003Ch2 id=\"what-breaks-or-gets-transformed\">What Breaks or Gets Transformed\u003C/h2>\n\u003Ch3 id=\"yaml-frontmatter\">YAML Frontmatter\u003C/h3>\n\u003Cp>Notion has no concept of frontmatter. If your document starts with:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">---\ntitle: My Document\n\u003Cspan class=\"hljs-section\">date: 2026-06-26\n---\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Notion imports this as plain text — the dashes become a divider block, and \u003Ccode>title: My Document\u003C/code> renders as a heading or prose depending on context. If you're importing docs that have frontmatter, strip it before importing, or use our \u003Ca href=\"/tools/markdown-to-notion\">Markdown to Notion converter\u003C/a>, which removes frontmatter automatically and warns you what was stripped.\u003C/p>\n\u003Ch3 id=\"tables\">Tables\u003C/h3>\n\u003Cp>Tables are the trickiest part. Notion renders them differently depending on context:\u003C/p>\n\u003Cul>\n\u003Cli>In the \u003Cstrong>body of a page\u003C/strong>, a Markdown table becomes a simple inline table (not a database)\u003C/li>\n\u003Cli>When \u003Cstrong>imported via file\u003C/strong>, tables often become Notion databases with property columns\u003C/li>\n\u003Cli>If the \u003Cstrong>separator row is missing\u003C/strong> (\u003Ccode>|---|---|\u003C/code>), the table may just render as pipe-separated text\u003C/li>\n\u003C/ul>\n\u003Cp>Notion is strict about the GFM table format. Missing or malformed separator rows reliably break table rendering.\u003C/p>\n\u003Cp>What Notion tables \u003Cstrong>don't\u003C/strong> support:\u003C/p>\n\u003Cul>\n\u003Cli>Column alignment (\u003Ccode>:---:\u003C/code> / \u003Ccode>---:\u003C/code> is ignored)\u003C/li>\n\u003Cli>Multi-line cells\u003C/li>\n\u003Cli>Colspan or rowspan\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"images\">Images\u003C/h3>\n\u003Cp>Image syntax (\u003Ccode>![alt](url)\u003C/code>) works for external URLs. If your images use relative paths (e.g., \u003Ccode>![chart](./images/chart.png)\u003C/code>), they'll break — Notion can't resolve relative filesystem paths. Convert relative paths to absolute URLs before importing.\u003C/p>\n\u003Ch3 id=\"html\">HTML\u003C/h3>\n\u003Cp>Notion strips HTML entirely. Any \u003Ccode><div>\u003C/code>, \u003Ccode><span>\u003C/code>, \u003Ccode><details>\u003C/code>, \u003Ccode><summary>\u003C/code>, or other HTML elements in your Markdown will disappear on import. If you're using HTML for collapsible sections, badges, or custom alignment, those won't survive.\u003C/p>\n\u003Ch3 id=\"mermaid-diagrams\">Mermaid Diagrams\u003C/h3>\n\u003Cp>Notion does not render Mermaid diagrams. A fenced code block tagged with \u003Ccode>mermaid\u003C/code> will import as a plain code block containing the diagram source — not a rendered diagram. This trips people up because GitHub, GitLab, and several documentation tools do render Mermaid natively.\u003C/p>\n\u003Cp>If you have Mermaid diagrams, your options are: export them as images and embed, or use Notion's native embed integration (which requires a third-party service).\u003C/p>\n\u003Ch3 id=\"footnotes\">Footnotes\u003C/h3>\n\u003Cp>Standard Markdown footnote syntax (\u003Ccode>[^1]\u003C/code>) isn't supported by Notion. On import, footnote references typically disappear and the footnote definitions render as plain text at the bottom of the page. Our converter inlines footnotes — replacing \u003Ccode>[^1]\u003C/code> references with the footnote text in italics — which is the most readable fallback.\u003C/p>\n\u003Ch3 id=\"github-style-alerts\">GitHub-Style Alerts\u003C/h3>\n\u003Cp>GitHub Flavored Markdown alerts like:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!NOTE]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is an important note.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>...render in GitHub as styled callout boxes, but Notion imports them as plain blockquotes. The \u003Ccode>[!NOTE]\u003C/code> text appears literally in the quote. In newer Notion workspaces you can manually convert the blockquote to a callout block after import, but it's a manual step.\u003C/p>\n\u003Ch2 id=\"exporting-markdown-from-notion\">Exporting Markdown from Notion\u003C/h2>\n\u003Cp>Notion's export (Page → Export → Markdown & CSV) produces reasonable Markdown, but with quirks to know about:\u003C/p>\n\u003Cp>\u003Cstrong>Tables export as CSV files\u003C/strong> — not inline Markdown tables. If your page contains a database, the export creates a separate \u003Ccode>.csv\u003C/code> file and links to it from the Markdown. This roundtrip doesn't work well for docs-as-code workflows where you expect embedded tables.\u003C/p>\n\u003Cp>\u003Cstrong>Internal page links\u003C/strong> export as full Notion URLs — not relative paths. An internal link to another Notion page becomes something like \u003Ccode>[Page Title](https://www.notion.so/workspace/abc123...)\u003C/code>. These links break when you move content out of Notion.\u003C/p>\n\u003Cp>\u003Cstrong>Callout blocks\u003C/strong> export as blockquotes with the emoji prepended as plain text.\u003C/p>\n\u003Cp>\u003Cstrong>Nested pages\u003C/strong> export as subdirectories. The folder structure maps to page hierarchy, which is useful if you want to mirror the Notion structure but inconvenient if you want a flat directory.\u003C/p>\n\u003Cp>\u003Cstrong>Whitespace\u003C/strong> in exported tables includes trailing spaces for column alignment. Most parsers handle this fine, but some produce artifacts.\u003C/p>\n\u003Ch2 id=\"notion-api-and-markdown\">Notion API and Markdown\u003C/h2>\n\u003Cp>If you're using the Notion API to create or update pages programmatically, you can't POST Markdown directly. The API uses Notion's own block format — each heading, paragraph, list item, and code block is a separate JSON object. You need to convert Markdown to block format before posting.\u003C/p>\n\u003Cp>This matters for teams automating documentation workflows: syncing a Git repo to Notion, generating pages from templates, or importing content on a schedule. The Notion API is capable, but it expects its own block format, not Markdown strings.\u003C/p>\n\u003Ch2 id=\"quick-reference-import-compatibility\">Quick Reference: Import Compatibility\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Markdown feature\u003C/th>\n\u003Cth>Imports correctly?\u003C/th>\n\u003Cth>Notes\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Headings H1–H3\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Bold, italic\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Inline code\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Fenced code blocks\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>Language labels preserved\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Unordered / ordered lists\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Checkboxes\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Links\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Blockquotes\u003C/td>\n\u003Ctd>Yes\u003C/td>\n\u003Ctd>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Tables (with separator row)\u003C/td>\n\u003Ctd>Mostly\u003C/td>\n\u003Ctd>No alignment, colspan\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>YAML frontmatter\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Renders as prose / divider\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Images (relative paths)\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Absolute URLs only\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>HTML\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Stripped entirely\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Mermaid diagrams\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Renders as plain code block\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Footnotes\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003Ctd>Definitions appear as text\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>GitHub-style alerts\u003C/td>\n\u003Ctd>Partial\u003C/td>\n\u003Ctd>Renders as plain blockquote\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"using-the-converter-tool\">Using the Converter Tool\u003C/h2>\n\u003Cp>If you're regularly moving content into Notion, our \u003Ca href=\"/tools/markdown-to-notion\">Markdown to Notion converter\u003C/a> handles the pre-processing:\u003C/p>\n\u003Cul>\n\u003Cli>Strips YAML frontmatter (with a warning listing what was removed)\u003C/li>\n\u003Cli>Inlines footnotes as italic text inline with the reference\u003C/li>\n\u003Cli>Converts GitHub-style alerts to labeled blockquotes\u003C/li>\n\u003Cli>Removes HTML tags (with a warning)\u003C/li>\n\u003Cli>Flags Mermaid diagrams so you can handle them manually\u003C/li>\n\u003C/ul>\n\u003Cp>Paste your Markdown on the left, get Notion-ready Markdown on the right. No signup required.\u003C/p>\n\u003Ch2 id=\"related-posts-and-tools\">Related Posts and Tools\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/tools/markdown-to-notion\">Markdown to Notion converter\u003C/a> — cleans up Markdown before importing\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown Across Platforms\u003C/a> — how Markdown behaves in GitHub, Obsidian, Confluence, and more\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/obsidian-vs-notion-vs-roam-note-taking-comparison\">Obsidian vs Notion vs Roam Research\u003C/a> — which note-taking tool fits your workflow\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-in-confluence-what-works\">Markdown in Confluence\u003C/a> — the same treatment for Confluence users\u003C/li>\n\u003Cli>\u003Ca href=\"/tools/html-to-markdown\">HTML to Markdown\u003C/a> — extract Markdown from Notion's HTML export\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31,34,37],{"id":16,"text":17,"level":18},"how-notion-handles-markdown-input","How Notion Handles Markdown Input",2,{"id":20,"text":21,"level":18},"what-converts-cleanly","What Converts Cleanly",{"id":23,"text":24,"level":18},"what-breaks-or-gets-transformed","What Breaks or Gets Transformed",{"id":26,"text":27,"level":18},"exporting-markdown-from-notion","Exporting Markdown from Notion",{"id":29,"text":30,"level":18},"notion-api-and-markdown","Notion API and Markdown",{"id":32,"text":33,"level":18},"quick-reference-import-compatibility","Quick Reference: Import Compatibility",{"id":35,"text":36,"level":18},"using-the-converter-tool","Using the Converter Tool",{"id":38,"text":39,"level":18},"related-posts-and-tools","Related Posts and Tools",[41,42],"markdown-to-notion","html-to-markdown",[44,53,63],{"slug":45,"title":46,"description":47,"excerpt":48,"date":49,"category":50,"author":10,"keywords":51,"readingMinutes":52},"markdown-in-confluence-what-works","Markdown in Confluence: What Actually Works, What Doesn't, and Workarounds","A practical guide to using Markdown in Confluence Cloud and Data Center — what converts cleanly, what breaks, and how to work around the limitations.","If you're a developer or technical writer who lives in Markdown, Confluence can feel like a wall. You write clean Markdown, paste it into Confluence, and something unexpected happens. Sometimes it…","2026-05-15","platform-guides","confluence markdown, confluence markdown support, confluence markdown editor, atlassian markdown, confluence paste markdown, confluence import markdown",7,{"slug":54,"title":55,"description":56,"excerpt":57,"date":58,"category":59,"author":60,"keywords":61,"readingMinutes":62},"markdown-platform-compatibility-guide","Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence","A practical Markdown compatibility guide for GitHub, Notion, Obsidian, Confluence, VS Code, and more. Includes a feature comparison table and platform-specific tips.","Markdown is everywhere — but Markdown is not the same everywhere. If you've ever carefully written a document with footnotes, custom HTML, or a nice callout block, only to paste it into a…","2026-04-30","Guide","Matthew Rathbone","markdown compatibility, markdown platforms, github markdown, notion markdown, obsidian markdown, confluence markdown, markdown comparison, markdown features by platform",8,{"slug":64,"title":65,"description":66,"excerpt":67,"date":68,"category":9,"author":10,"keywords":69,"readingMinutes":12},"markdown-to-slack-formatting-guide","Markdown to Slack Formatting: What Actually Works (mrkdwn Explained)","Slack doesn't render standard Markdown — it uses its own mrkdwn format. Here's the full syntax mapping, what breaks (tables, headings, images), and how to convert reliably.","If you've ever pasted a chunk of Markdown into Slack expecting headings and tables to show up nicely, you've already learned the hard way: Slack doesn't speak Markdown. It has its own lookalike…","2026-07-10","markdown to slack, slack mrkdwn, slack markdown formatting, slack message formatting, slack markdown syntax, convert markdown to slack, slack markdown tables",1792184946871]