[{"data":1,"prerenderedAt":72},["Reactive",2],{"blog-post-markdown-platform-compatibility-guide":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":43,"related":47},"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,"\u003Cp>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 different tool and watch it break, you know the pain.\u003C/p>\n\u003Cp>This guide is a practical reference for which Markdown features work in the tools most developers and technical writers actually use. Not theory — just what works, what doesn't, and what you need to do differently on each platform.\u003C/p>\n\u003Ch2 id=\"quick-comparison-table\">Quick Comparison Table\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Feature\u003C/th>\n\u003Cth>GitHub\u003C/th>\n\u003Cth>GitLab\u003C/th>\n\u003Cth>Notion\u003C/th>\n\u003Cth>Obsidian\u003C/th>\n\u003Cth>Confluence\u003C/th>\n\u003Cth>VS Code\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Basic formatting (bold, italic)\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Headings\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Fenced code blocks\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Syntax highlighting\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>⚠️ limited\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Tables\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Task lists\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Strikethrough\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Footnotes\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>⚠️ varies\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Inline HTML\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>⚠️ partial\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Emoji shortcodes (\u003Ccode>:smile:\u003C/code>)\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Callouts / Admonitions\u003C/td>\n\u003Ctd>✅ (alerts)\u003C/td>\n\u003Ctd>⚠️\u003C/td>\n\u003Ctd>✅ (native)\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Math / LaTeX\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>⚠️ plugin\u003C/td>\n\u003Ctd>⚠️ extension\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Definition lists\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Mermaid diagrams\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003Ctd>✅ (plugin)\u003C/td>\n\u003Ctd>⚠️ plugin\u003C/td>\n\u003Ctd>✅ (extension)\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Auto table of contents\u003C/td>\n\u003Ctd>✅ (sidebar)\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>✅ (native)\u003C/td>\n\u003Ctd>✅ (plugin)\u003C/td>\n\u003Ctd>✅\u003C/td>\n\u003Ctd>❌\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Cp>✅ = fully supported   ⚠️ = partial/requires setup   ❌ = not supported\u003C/p>\n\u003Cp>Now let's go platform by platform.\u003C/p>\n\u003Chr>\n\u003Ch2 id=\"github\">GitHub\u003C/h2>\n\u003Cp>GitHub uses \u003Cstrong>GitHub Flavored Markdown (GFM)\u003C/strong>, which extends CommonMark with a set of additional features. It's the most widely referenced flavor of Markdown and the one most tools try to be compatible with.\u003C/p>\n\u003Ch3 id=\"what-github-does-well\">What GitHub does well\u003C/h3>\n\u003Cp>\u003Cstrong>Tables\u003C/strong> work without any special setup:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">| Column 1 | Column 2 | Column 3 |\n|----------|----------|----------|\n| Cell     | Cell     | Cell     |\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Task lists\u003C/strong> render as interactive checkboxes in issues and pull requests:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-bullet\">-\u003C/span> [x] Done\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [ ] Not done\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Syntax-highlighted code blocks\u003C/strong> — just add the language name after the opening backticks:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-code\">```python\ndef hello():\n    print("Hello, world!")\n```\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Alerts/callouts\u003C/strong> were added in 2023 and use a blockquote-based syntax:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!NOTE]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is a note.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!WARNING]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is a warning.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!TIP]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is a tip.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Mermaid diagrams\u003C/strong> work directly in code fences:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-code\">```mermaid\ngraph TD;\n    A-->B;\n    B-->C;\n```\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Footnotes\u003C/strong> are supported:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">Here is a claim.[^1]\n\n[\u003Cspan class=\"hljs-symbol\">^1\u003C/span>]: \u003Cspan class=\"hljs-link\">Here is the footnote.\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"github-gotchas\">GitHub gotchas\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Anchor link generation\u003C/strong>: GitHub lowercases all characters and replaces spaces with hyphens. Special characters (except hyphens and underscores) are removed. \u003Ccode>## API & SDK\u003C/code> becomes \u003Ccode>#api--sdk\u003C/code>.\u003C/li>\n\u003Cli>\u003Cstrong>Inline HTML is allowed\u003C/strong> but script tags and most event attributes are stripped for security.\u003C/li>\n\u003Cli>\u003Cstrong>Indentation in lists\u003C/strong> matters — use 4 spaces (not 2) if you want nested paragraphs inside a list item.\u003C/li>\n\u003Cli>\u003Cstrong>Definition lists\u003C/strong> (\u003Ccode><dl>\u003C/code>, \u003Ccode><dt>\u003C/code>, \u003Ccode><dd>\u003C/code>) are \u003Cem>not\u003C/em> part of GFM — use a table instead.\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"gitlab\">GitLab\u003C/h2>\n\u003Cp>GitLab also uses GFM as a base but adds its own extensions, some of which are quite powerful.\u003C/p>\n\u003Ch3 id=\"gitlab-extras\">GitLab extras\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Superscript and subscript\u003C/strong>: \u003Ccode>x^2^\u003C/code> and \u003Ccode>H~2~O\u003C/code>\u003C/li>\n\u003Cli>\u003Cstrong>Color chips\u003C/strong>: inline hex colors like \u003Ccode>`#FF0000`\u003C/code> render a color swatch in merge requests\u003C/li>\n\u003Cli>\u003Cstrong>Diagrams\u003C/strong>: Mermaid, PlantUML, and Kroki are all supported\u003C/li>\n\u003Cli>\u003Cstrong>Definition lists\u003C/strong>: ✅ (unlike GitHub)\u003C/li>\n\u003Cli>\u003Cstrong>Table of contents\u003C/strong>: Add \u003Ccode>[[_TOC_]]\u003C/code> anywhere in a document to auto-generate one\u003C/li>\n\u003Cli>\u003Cstrong>Markdown in epics/issues\u003C/strong>: supports most GFM plus GitLab-specific references (\u003Ccode>#123\u003C/code>, \u003Ccode>@username\u003C/code>, \u003Ccode>!456\u003C/code>)\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"gitlab-gotchas\">GitLab gotchas\u003C/h3>\n\u003Cul>\n\u003Cli>Many extended features only work in GitLab wiki pages and repository files, not in issue descriptions everywhere.\u003C/li>\n\u003Cli>Callout blocks aren't native like GitHub's \u003Ccode>[!NOTE]\u003C/code> syntax — you need to use raw HTML or CSS classes.\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"notion\">Notion\u003C/h2>\n\u003Cp>Notion has its own Markdown-like editor that isn't really Markdown — it's a block-based editor that \u003Cem>supports\u003C/em> Markdown shortcuts for input but stores content internally as blocks.\u003C/p>\n\u003Ch3 id=\"what-notion-supports\">What Notion supports\u003C/h3>\n\u003Cul>\n\u003Cli>Basic formatting (bold, italic, strikethrough, inline code)\u003C/li>\n\u003Cli>Headings, bulleted and numbered lists, task lists\u003C/li>\n\u003Cli>Code blocks with syntax highlighting (choose language from dropdown)\u003C/li>\n\u003Cli>Tables (as a native block type)\u003C/li>\n\u003Cli>Math blocks using LaTeX (via \u003Ccode>/math\u003C/code> or \u003Ccode>/equation\u003C/code>)\u003C/li>\n\u003Cli>Native callout blocks (different from Markdown syntax)\u003C/li>\n\u003Cli>Toggles (collapsible sections) — no Markdown equivalent\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"notion-markdown-importexport\">Notion Markdown import/export\u003C/h3>\n\u003Cp>When you \u003Cstrong>import Markdown\u003C/strong> into Notion, it converts what it can into blocks. When you \u003Cstrong>export to Markdown\u003C/strong>, it converts blocks back — but you'll lose Notion-specific features (toggles become plain text, callouts may simplify).\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- This works when imported into Notion -->\n\u003Cspan class=\"hljs-strong\">**Bold**\u003C/span> and \u003Cspan class=\"hljs-emphasis\">*italic*\u003C/span> and ~~strikethrough~~\n\n\u003Cspan class=\"hljs-section\"># Heading 1\u003C/span>\n\u003Cspan class=\"hljs-section\">## Heading 2\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [x] Task done\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [ ] Task pending\n\n| Col A | Col B |\n|-------|-------|\n| 1     | 2     |\n\u003C/code>\u003C/pre>\u003Ch3 id=\"notion-gotchas\">Notion gotchas\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>No footnotes\u003C/strong> — there's no native footnote block.\u003C/li>\n\u003Cli>\u003Cstrong>No inline HTML\u003C/strong> — all HTML is stripped.\u003C/li>\n\u003Cli>\u003Cstrong>Emoji shortcodes\u003C/strong> work (\u003Ccode>:thumbsup:\u003C/code> renders 👍) but not all codes.\u003C/li>\n\u003Cli>\u003Cstrong>Callout blocks\u003C/strong> are native Notion features — they don't map to any standard Markdown syntax. When exporting, they typically become blockquotes.\u003C/li>\n\u003Cli>\u003Cstrong>Links\u003C/strong> behave differently: Notion links to other Notion pages use \u003Ccode>@\u003C/code> mentions in the editor, not Markdown links.\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"obsidian\">Obsidian\u003C/h2>\n\u003Cp>Obsidian uses \u003Cstrong>CommonMark\u003C/strong> as its base with GFM extensions added on top. It's designed for personal knowledge management, so it has features optimized for linking between notes.\u003C/p>\n\u003Ch3 id=\"obsidian-specific-features\">Obsidian-specific features\u003C/h3>\n\u003Cp>\u003Cstrong>Wiki-links\u003C/strong> for linking between notes:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">[[Another Note]]\n[[Folder/Note|Custom display text]]\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Callouts\u003C/strong> use a slightly different syntax from GitHub:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!NOTE]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is a note callout.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!WARNING] Custom title\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This is a warning with a custom title.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Tags\u003C/strong> in frontmatter and inline:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">---\n\u003Cspan class=\"hljs-section\">tags: [markdown, writing]\n---\u003C/span>\n\nThis is #tagged inline too.\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Footnotes\u003C/strong> are fully supported:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">Here is text.[^note]\n\n[\u003Cspan class=\"hljs-symbol\">^note\u003C/span>]: \u003Cspan class=\"hljs-link\">Footnote content.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Math\u003C/strong> works with \u003Ccode>$\u003C/code> (inline) and \u003Ccode>$$\u003C/code> (block):\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">Inline: $E = mc^2$\n\nBlock:\n$$\n\\frac{d}{dx}\\left( \\int\u003Cspan class=\"hljs-emphasis\">_{0}^{x} f(u)\\,du\\right)=f(x)\n$$\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"obsidian-gotchas\">Obsidian gotchas\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Inline HTML\u003C/strong> is partially supported — basic tags like \u003Ccode><u>\u003C/code>, \u003Ccode><br>\u003C/code>, \u003Ccode><sup>\u003C/code>, \u003Ccode><sub>\u003C/code> usually work. Script tags and styles are blocked.\u003C/li>\n\u003Cli>\u003Cstrong>Mermaid diagrams\u003C/strong> require the Mermaid plugin (or are built-in depending on your Obsidian version).\u003C/li>\n\u003Cli>\u003Cstrong>Wiki-links don't work outside Obsidian\u003C/strong> — if you share \u003Ccode>.md\u003C/code> files with others, these links will break.\u003C/li>\n\u003Cli>\u003Cstrong>Strikethrough\u003C/strong> requires GFM mode (enabled by default).\u003C/li>\n\u003Cli>The \u003Cstrong>Live Preview\u003C/strong> mode and \u003Cstrong>Source mode\u003C/strong> render things slightly differently — always check your callouts and tables in reading view.\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"confluence\">Confluence\u003C/h2>\n\u003Cp>Confluence has two editors: the \u003Cstrong>legacy wiki markup editor\u003C/strong> and the newer \u003Cstrong>Confluence Cloud editor\u003C/strong> (block-based). Markdown support depends on which you're using.\u003C/p>\n\u003Ch3 id=\"confluence-cloud-new-editor\">Confluence Cloud (new editor)\u003C/h3>\n\u003Cp>Confluence Cloud supports importing Markdown via the \u003Ccode>/\u003C/code> command — paste your Markdown and Confluence will convert it. Native Markdown \u003Cem>authoring\u003C/em> is limited; the editor is block-based.\u003C/p>\n\u003Cp>\u003Cstrong>Supported via import:\u003C/strong>\u003C/p>\n\u003Cul>\n\u003Cli>Headings, bold, italic, strikethrough\u003C/li>\n\u003Cli>Ordered and unordered lists\u003C/li>\n\u003Cli>Fenced code blocks\u003C/li>\n\u003Cli>Tables (with caveats — complex tables may not import cleanly)\u003C/li>\n\u003Cli>Links and images\u003C/li>\n\u003C/ul>\n\u003Cp>\u003Cstrong>Not supported or converted differently:\u003C/strong>\u003C/p>\n\u003Cul>\n\u003Cli>Task lists — become plain list items, not Confluence action items\u003C/li>\n\u003Cli>Footnotes — dropped on import\u003C/li>\n\u003Cli>Inline HTML — stripped\u003C/li>\n\u003Cli>Callouts — become plain blockquotes\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"confluence-gotchas\">Confluence gotchas\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Tables with merged cells\u003C/strong> will not import from Markdown at all — Markdown tables can't represent cell merging.\u003C/li>\n\u003Cli>\u003Cstrong>Macros\u003C/strong> (like the \u003Ccode>info\u003C/code>, \u003Ccode>warning\u003C/code>, and \u003Ccode>note\u003C/code> panels) are Confluence-specific and have no Markdown equivalent.\u003C/li>\n\u003Cli>\u003Cstrong>Syntax highlighting\u003C/strong> works in code blocks, but you need to select the language within the Confluence UI after importing.\u003C/li>\n\u003Cli>If you're on \u003Cstrong>Confluence Data Center\u003C/strong> (self-hosted), the behavior varies by version and installed plugins.\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"vs-code\">VS Code\u003C/h2>\n\u003Cp>VS Code's built-in Markdown preview renders \u003Cstrong>CommonMark\u003C/strong> spec, not full GFM. It's useful for quick previewing but has some limitations.\u003C/p>\n\u003Ch3 id=\"what-works-in-vs-code-preview\">What works in VS Code preview\u003C/h3>\n\u003Cul>\n\u003Cli>Headings, basic formatting, lists, links, images\u003C/li>\n\u003Cli>Fenced code blocks (with syntax highlighting)\u003C/li>\n\u003Cli>Tables\u003C/li>\n\u003Cli>Strikethrough (via the \u003Ccode>markdown-it\u003C/code> GFM extension, enabled by default)\u003C/li>\n\u003Cli>Math (with the Markdown Math extension or built into newer VS Code versions)\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"what-doesnt-work-out-of-the-box\">What doesn't work out of the box\u003C/h3>\n\u003Cul>\n\u003Cli>Task list checkboxes don't render as interactive checkboxes (they display correctly but aren't clickable)\u003C/li>\n\u003Cli>Footnotes require an extension\u003C/li>\n\u003Cli>Emoji shortcodes (\u003Ccode>:smile:\u003C/code>) are not rendered\u003C/li>\n\u003Cli>Mermaid diagrams require the \u003Cstrong>Markdown Preview Mermaid Support\u003C/strong> extension\u003C/li>\n\u003Cli>GitHub-specific alert syntax (\u003Ccode>> [!NOTE]\u003C/code>) requires the \u003Cstrong>Markdown Alert\u003C/strong> extension\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"recommended-vs-code-extensions-for-markdown\">Recommended VS Code extensions for Markdown\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Markdown All in One\u003C/strong> — TOC generation, keyboard shortcuts, list editing\u003C/li>\n\u003Cli>\u003Cstrong>Markdown Preview GitHub Styling\u003C/strong> — makes preview look like GitHub\u003C/li>\n\u003Cli>\u003Cstrong>markdownlint\u003C/strong> — lints your Markdown for common errors\u003C/li>\n\u003Cli>\u003Cstrong>Markdown Preview Mermaid Support\u003C/strong> — diagram rendering\u003C/li>\n\u003C/ul>\n\u003Chr>\n\u003Ch2 id=\"writing-portable-markdown\">Writing Portable Markdown\u003C/h2>\n\u003Cp>If your documents need to work across multiple platforms, follow these rules:\u003C/p>\n\u003Ch3 id=\"safe-everywhere\">Safe everywhere\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># Headings (H1–H4)\u003C/span>\n\u003Cspan class=\"hljs-strong\">**Bold**\u003C/span> and \u003Cspan class=\"hljs-emphasis\">*italic*\u003C/span>\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> Unordered lists\n\u003Cspan class=\"hljs-bullet\">1.\u003C/span> Numbered lists\n[\u003Cspan class=\"hljs-string\">Links\u003C/span>](\u003Cspan class=\"hljs-link\">https://example.com\u003C/span>)\n![\u003Cspan class=\"hljs-string\">Images\u003C/span>](\u003Cspan class=\"hljs-link\">image.png\u003C/span>)\n\u003Cspan class=\"hljs-code\">`Inline code`\u003C/span>\n\\\u003Cspan class=\"hljs-code\">`\\`\u003C/span>\\\u003Cspan class=\"hljs-code\">`fenced code blocks\\`\u003C/span>\\\u003Cspan class=\"hljs-code\">`\\`\u003C/span>\n| Simple | Tables |\n\u003C/code>\u003C/pre>\u003Ch3 id=\"use-with-caution-works-in-most-places-not-all\">Use with caution (works in most places, not all)\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">~~Strikethrough~~       <!-- Not in some older renderers -->\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [x] Task lists       <!-- Breaks in Confluence, some renderers -->\n[\u003Cspan class=\"hljs-string\">Link\u003C/span>][\u003Cspan class=\"hljs-symbol\">ref\u003C/span>]            <!-- Reference-style links work everywhere but are less common -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"avoid-for-portability\">Avoid for portability\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">[^footnote]            <!-- Only GitHub, GitLab, Obsidian -->\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">div\u003C/span>>\u003C/span>\u003C/span>HTML blocks\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">div\u003C/span>>\u003C/span>\u003C/span> <!-- Stripped in Notion, Confluence -->\n:emoji:                <!-- VS Code, older renderers don't support -->\n\u003Cspan class=\"hljs-quote\">> [!NOTE] alerts       <!-- Only GitHub, Obsidian -->\u003C/span>\n[[wiki-links]]         <!-- Only Obsidian -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"tip-use-our-tools-to-help\">Tip: Use our tools to help\u003C/h3>\n\u003Cp>If you're moving content between formats, our \u003Ca href=\"/tools/html-to-markdown\">HTML to Markdown converter\u003C/a> and \u003Ca href=\"/tools/markdown-to-html\">Markdown to HTML tool\u003C/a> can help bridge the gap. For table conversion, \u003Ca href=\"/tools/markdown-to-csv\">Markdown Table → CSV\u003C/a> makes it easy to pull data into spreadsheets.\u003C/p>\n\u003Chr>\n\u003Ch2 id=\"summary\">Summary\u003C/h2>\n\u003Cp>The short version:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Most portable\u003C/strong>: Basic formatting + tables + fenced code blocks work everywhere\u003C/li>\n\u003Cli>\u003Cstrong>GitHub is the safest bet\u003C/strong> for extended features (footnotes, task lists, alerts)\u003C/li>\n\u003Cli>\u003Cstrong>Notion and Confluence\u003C/strong> are block-based editors — they import Markdown but don't author it natively; expect some feature loss\u003C/li>\n\u003Cli>\u003Cstrong>Obsidian\u003C/strong> is the most feature-rich for local Markdown authoring but has proprietary extensions that break portability\u003C/li>\n\u003Cli>\u003Cstrong>VS Code\u003C/strong> is CommonMark only — add extensions for anything beyond basics\u003C/li>\n\u003C/ul>\n\u003Cp>For platform-specific deep dives, see also:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/how-to-create-table-of-contents-in-markdown\">How to create a table of contents in Markdown\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-tables-advanced-features-and-styling-guide\">Markdown tables: advanced features and styling\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-admonitions-callouts-complete-guide\">Markdown callouts and admonitions\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/footnotes-in-markdown\">Footnotes in Markdown\u003C/a>\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31,34,37,40],{"id":16,"text":17,"level":18},"quick-comparison-table","Quick Comparison Table",2,{"id":20,"text":21,"level":18},"github","GitHub",{"id":23,"text":24,"level":18},"gitlab","GitLab",{"id":26,"text":27,"level":18},"notion","Notion",{"id":29,"text":30,"level":18},"obsidian","Obsidian",{"id":32,"text":33,"level":18},"confluence","Confluence",{"id":35,"text":36,"level":18},"vs-code","VS Code",{"id":38,"text":39,"level":18},"writing-portable-markdown","Writing Portable Markdown",{"id":41,"text":42,"level":18},"summary","Summary",[44,45,46],"html-to-markdown","markdown-to-html","markdown-to-csv",[48,57,64],{"slug":49,"title":50,"description":51,"excerpt":52,"date":53,"category":54,"author":55,"keywords":56,"readingMinutes":12},"markdown-image-sizing-alignment-across-platforms","Markdown Image Sizing and Alignment Across Platforms: What Actually Works","Wrapping an image in a sized, centered \u003Cimg> tag works great in GitHub — but paste that same Markdown into Notion or Slack and the HTML just vanishes. Here's which platforms honor inline HTML for images, which have their own separate syntax, and which need attachments instead.","Standard Markdown's image syntax — — has no way to control size or alignment. There's no width=, no center, nothing. So the moment you need a smaller image, or one centered on the page instead of…","2026-09-04","workflows","Matt Rathbone","markdown image size, markdown image alignment, resize image markdown, center image markdown, obsidian image size, notion image markdown, markdown image html platforms",{"slug":58,"title":59,"description":60,"excerpt":61,"date":62,"category":54,"author":55,"keywords":63,"readingMinutes":12},"markdown-math-rendering-across-platforms","Markdown Math Rendering Across Platforms: Where LaTeX Actually Works","The $...$ / $$...$$ LaTeX convention for math in Markdown looks identical everywhere, but whether it renders at all — and which engine renders it — varies enormously across GitHub, GitLab, Obsidian, Notion, Jekyll, Hugo, Confluence, and Slack. Here's what's real.","Wrap a formula in dollar signs — $E = mc^2$ — and on some platforms you get a beautifully typeset equation. On others you get the literal text $E = mc^2$ sitting there unrendered, because the…","2026-08-21","markdown math rendering, latex markdown platforms, katex vs mathjax, github math support, notion math equations, jekyll math plugin, hugo katex, confluence math",{"slug":65,"title":66,"description":67,"excerpt":68,"date":69,"category":54,"author":55,"keywords":70,"readingMinutes":71},"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","markdown notion, notion markdown import, notion markdown export, notion markdown support, paste markdown notion, notion markdown rendering",6,1792184946708]