Markdown dialect portability

Markdown is not one language. It is a family of dialects — CommonMark, GitHub Flavored Markdown (GFM), Obsidian Flavored Markdown, pandoc Markdown, MultiMarkdown, and others — that share a core but differ in extensions, edge-case parsing, and even the meaning of individual characters. A document that renders one way in one tool can render differently (or not at all) in another. Portability is a property you design for, not a default.

The dialect stack

CommonMark is the rigorous core: a formal specification (current 0.31.2, 2024) that pins down parsing rules Markdown’s original 2004 description left ambiguous. ¹ It covers blocks, inlines, emphasis, links, code, and HTML — but not tables, footnotes, strikethrough, or task lists.

GitHub Flavored Markdown extends CommonMark with tables, task-list items, strikethrough (~~text~~), and autolinked URLs. ² These four extensions are the most widely supported beyond the core, but they are still extensions — a plain CommonMark renderer ignores them.

Obsidian Flavored Markdown is CommonMark + GFM + a large set of proprietary extensions: wikilinks ([[Note]]), embeds (![[Note]]), block IDs (^id), callouts (> [!warning]), highlights (==text==), comments (%% %%), image-size hints, nested tags, and app-specific frontmatter fields. ³ Most of these have no meaning outside Obsidian; pandoc renders the majority as literal text.

The escaping problem

Every dialect reserves its own metacharacters, and the escape hatch is always the backslash — but which characters need escaping depends on which extensions are active. GFM §6.5 makes ~ meaningful (strikethrough), so a literal tilde in prose (~/.config, ~50 calls) must be written \~ or it silently reformats. Inline math (a common extension, not CommonMark) makes $ meaningful, so literal dollar amounts need \$. A vault written without this discipline renders fine in its home tool until a header, paragraph, or link happens to contain a reserved pair — at which point the corruption is silent and propagates (the 2026-08-17 grimoire sweep escaped literal ~ and $ across hundreds of pages after exactly this failure). ^{4 5}

Obsidian-specific loss

Karl Voit’s 2026 experiment (LLM-generated, self-flagged as unverified — treat as a checklist, not gospel) catalogs what survives a pandoc conversion from Obsidian to HTML: ⁶

• Survives: headings, lists, footnotes, plain text of tags, task checkboxes (as GFM), standard YAML frontmatter (title/date).
• Degrades: wikilinks → literal [[brackets]]; highlights → literal ==; math → broken LaTeX without --mathjax; Mermaid → raw code block.
• Lost entirely: embeds/transclusion (dynamic), block references, callout semantics and styling, %% comments (worse — exposed as text), image size hints, nested-tag hierarchy, aliases/cssclasses metadata, Excalidraw drawings, Dataview/Templater/Kanban plugin syntax.
• Not in the files at all: graph view, backlinks, search, workspaces, canvas — app-level state, not document content.

Voit’s broader argument (Markdown Is a Disaster) is that this is not an Obsidian problem but a Markdown problem: the ecosystem has no superset standard, so every tool’s flavor is a local maximum and every migration is a partial translation. His recommended mitigations: audit syntax usage before committing to a tool, prefer standard links over wikilinks when interoperability matters, serialize dynamic content before export, and accept that some features have no lossless conversion.

Practical rules for a portable vault

1. Escape reserved characters in prose — \~, \$, and any other metacharacter your renderer’s extensions claim. Do it at authoring time; retrofitting is a sweep.
2. Know which dialect layer each construct lives in. CommonMark core is safe nearly everywhere. GFM extras are safe on GitHub and most modern renderers. Tool-specific syntax (wikilinks, callouts, Dataview) is a lock-in decision — use it deliberately.
3. Keep a syntax sample file — one note containing every construct you use, so a migration tool’s failures are immediately visible (Voit’s practice).
4. Prefer vendor-neutral fallbacks — ![alt](path) with separate sizing over ![[img|300]]; standard [text](file.md) links where the graph benefits of wikilinks aren’t needed.

Related pages

• obsidian-flavored-markdown — the raw spec extract for Obsidian’s dialect
• gemini-compatible-markdown — gemtext: a deliberately minimal line-oriented dialect
• quartz-static-site-generator — publishing pipeline where dialect mismatches surface at build time
• robust-file-naming — adjacent discipline: naming files so they survive tool changes
• coldcard-entropy-incident-2026 — the 2026-08-17 vault-corruption incident that motivated this page (strikethrough from unescaped ~)

Sources

• 2004 — CommonMark Spec 0.31.2
• 2019 — GitHub Flavored Markdown Spec 0.29-gfm
• 2025 — Markdown Is a Disaster — Karl Voit
• Karl Voit 2026 — Potential Markdown Data Loss When You Will Move Away from Obsidian (MIGHT BE FALSE)

Footnotes

1. 2004 — CommonMark Spec 0.31.2 ↩

2. 2019 — GitHub Flavored Markdown Spec 0.29-gfm ↩

3. Karl Voit 2026 — Potential Markdown Data Loss When You Will Move Away from Obsidian (MIGHT BE FALSE) ↩

4. 2019 — GitHub Flavored Markdown Spec 0.29-gfm ↩

5. 2004 — CommonMark Spec 0.31.2 ↩

6. Karl Voit 2026 — Potential Markdown Data Loss When You Will Move Away from Obsidian (MIGHT BE FALSE) ↩