Markdown Flavors
Markdown is not one language but a family of dialects. Three matter to this vault: CommonMark (the base spec), GitHub Flavored Markdown (what repos render), and Obsidian Flavored Markdown (what the garden is written in). Knowing which dialect you’re writing determines what links, embeds, and structure survive the trip between them.
The family tree
- Original Markdown (2004, John Gruber) — the perl script; intentionally unspecified at edges (nested lists, indentation rules). Every ambiguity below exists because the original left them open.
- CommonMark — the 2014 standardization effort (John MacFarlane et al.): a rigorous, testable spec of the core syntax. No tables, no task lists, no strikethrough — deliberately minimal.
- GitHub Flavored Markdown — CommonMark plus a small closed set of extensions (formal spec captured, v0.29-gfm): tables, task list items (
- [ ]), strikethrough (~~x~~), autolinks, disallowed raw HTML. “A strict superset of CommonMark.” - Obsidian Flavored Markdown — CommonMark/GFM base plus an open set of vault extensions: wikilinks, embeds, tags, callouts, properties. The garden’s native dialect.
The dialect ladder
CommonMark ⊂ GFM ⊂ OFM (roughly — Obsidian accepts GFM tables/task lists and adds vault syntax). Content written down the ladder always renders; content written up the ladder loses its extensions — an OFM wikilink in a GitHub README renders literally.
Where each flavor is the law
| Context | Flavor | Why |
|---|---|---|
| Vault notes (this garden) | OFM | wikilink graph, embeds, callouts, publish: true frontmatter |
Repo docs (_specs/, READMEs) | GFM | what GitHub/Gitea render; CommonMark-safe subset for portability |
| Tool output, chat, CLIs | CommonMark subset | maximal compatibility — every renderer handles the core |
Portability rules (the practical part)
- Wikilinks
[[Note]]are vault-only — they render literally outside Obsidian. Cross-boundary docs use[text](url)with the published slug. - OFM embeds (
![[...]]),%%comments%%,==highlights==are vault-only too; strip before pasting into repo docs. - GFM tables/task lists are safe everywhere markdown is rendered by a modern tool — the 2019-frozen GFM spec (tables,
- [ ],~~strike~~, autolinks) is the de-facto common ground of renderers. - Frontmatter (YAML) is understood by Obsidian, Quartz (this site’s engine), and most SSGs — but is not part of any Markdown spec; it’s a convention layered on top.
- The GFM spec is frozen at 0.29-gfm (2019); GitHub the product has moved on (alerts
> [!NOTE], math, Mermaid) beyond its own spec — spec-compliance ≠ what GitHub renders today.
Open
- (open: the GFM spec capture documents the 2019 frozen state — GitHub’s live renderer adds math/Mermaid/alerts; note the drift when it bites)
- (open: Quartz OFM-compat layer — which OFM features survive publishing? (callouts and wikilinks do; verify embeds vs the site engine))
Related: Obsidian · digital garden