Markdown is a family of closely related dialects. The core idea is stable, but editors, static-site tools, and repos add their own extensions. The practical question is not “which Markdown?” but “which subset and extensions are we standardising on for our workflow” - commonmark.org 
# The landscape
- CommonMark is the baseline specification that removes ambiguity from early Markdown behaviour. Many tools implement/build on it - commonmark.org
- GitHub Flavored Markdown (GFM) extends CommonMark with task lists, tables, autolinks, strikethrough, and footnotes. It is the de facto default for repos, issues, and PRs - github.github.com
- Pandoc Markdown is a superset with powerful extras like citations, cross-refs, and fenced divs, aimed at multi-format publishing pipelines - pandoc.org
- MultiMarkdown and kramdown add features popular in blogs and static sites. Jekyll defaults to kramdown. Hugo uses Goldmark (CommonMark compliant with options) - jekyllrb.com - gohugo.io
- Editor flavours exist. Obsidian adds wikilinks and callouts. VS Code supports GFM preview and linting. Many note apps have small, non-standard affordances - obsidian.md - code.visualstudio.com
- MDX mixes Markdown and JSX for component docs. Useful in React sites, but not ideal for general prose intended to round-trip through multiple tools - mdxjs.com
# Is GFM the only real choice?
GFM is the most interoperable default for repos and developer tooling. We aim to have our documents and wiki pages live in git, are may well be reviewed in PRs, or must render predictably on GitHub/GitLab/Gitea, GFM gives us task lists, tables, and fenced code info string.
For teams that also publish to PDF/DOCX/Slides, keep the source in GFM and let the build pipeline use Pandoc-specific extensions at compile time - gitea.com
# What to standardise on - Adopt CommonMark + GFM as the canonical authoring baseline. - Permit only a small, documented subset: headings, emphasis, links, images, fenced code with language, autolinks, strikethrough, tables, task lists, footnotes. - Prefer ASCII punctuation for syntax. Allow Unicode in prose where it adds clarity. - Discourage inline HTML except for deliberate, reviewed cases. - Keep one `#` heading per page. Keep lists flat. Link out for depth.
This keeps documents portable across editors, CI, and hosting while remaining pleasant to write.
# Being flexible and tolerant (age of AI + Pandoc) AI outputs and human habits will drift across dialects. Aim for “flexible-in, strict-out.” - Accept many inputs. Detect flavour heuristically. - Normalise every save or on commit with a formatter. Use Pandoc or a Markdown formatter to canonicalise to your GFM subset. - Lint in CI. Enforce your subset with markdownlint or remark rules. Fail helpfully with auto-fix suggestions. - Round-trip safely. If contributors use Pandoc features, let the pipeline convert them to nearest GFM or preserve them in fenced blocks with clear notes. - Keep semantics out of prose. If you need structure for agents, attach it as Yam or Kson alongside the `.md`, rather than inventing inline syntax.
Example normalisation: - Read any flavour, write GFM
pandoc input.md -f markdown -t gfm -o output.md