Choosing a Markdown Flavor for Technical Docs: CommonMark, GFM, or MultiMarkdown

Decision: Which Markdown flavor to adopt for your engineering documentation?

State the problem: you need tables, task lists, and optionally footnotes while keeping the source portable across renderers used in your CI/CD pipeline, wikis, and static site generators.

Constraints

• Must render correctly on GitHub/GitLab (which use GFM).
• Should remain usable in strict CommonMark environments for archival or PDF generation.
• Optional need for footnotes or bibliography.

Comparison of supported features

Feature	CommonMark	GFM	MultiMarkdown
Tables	✗	✓	✓
Task lists	✗	✓	✓
Footnotes	✗	✗	✓
Raw HTML blocks	✓	✓	✓
Strikethrough	✗	✓	✓

Trade‑offs

CommonMark gives the highest portability and strict spec compliance but lacks tables, task lists, and footnotes. GFM adds tables, task lists, and strikethrough while staying close to CommonMark, so most renderers that understand CommonMark will also handle GFM tables and task lists. MultiMarkdown extends further with footnotes, citations, and metadata blocks, but requires a parser that understands its extensions (e.g., multimarkdown, pandoc with the markdown_mmd reader) and has a larger footprint; it is less universally supported in lightweight previewers.

Concrete implementation and validation

Below is a minimal Markdown file that exercises the features you might need. Save it as example.md.

# Example Doc

| Header A | Header B |
|----------|----------|
| cell 1   | cell 2   |

- [ ] pending task
- [x] completed task

This sentence has a footnote.[^1]

[^1]: This is the footnote text.

<div style="color:red">Red HTML block</div>

Validation steps

1. Render with a GFM‑aware processor (e.g., markdown-it with the table and tasklist plugins). Run:

   npx markdown-it example.md --html --plugin markdown-it-table --plugin markdown-it-tasklist > gfm.html

   Check that gfm.html contains a <table> element and that the list items render as <input type="checkbox"> (checked/unchecked).
2. Render with a strict CommonMark parser (e.g., commonmark CLI). Run:

   commonmark example.md > common.html

   Verify that the table and task list appear as plain text (no table markup, no checkboxes) – this shows the loss of those features.
3. Render with MultiMarkdown (or pandoc in MMD mode). Run:

   pandoc -f markdown_mmd example.md -t html -o mmd.html

   Inspect mmd.html for a footnote section (<li> inside <ol>) and for the table and task list as expected.

Practical way to check the result: open the generated HTML files in a browser and look for the expected elements. If the elements are missing, the processor does not support that feature.

Limitations and mitigation

• Raw HTML blocks are preserved in all three flavors but may break non‑HTML outputs (PDF, EPUB). Mitigate by limiting raw HTML to decorative wrappers or by providing fallback Markdown.
• GFM is not an independent standard; future changes in GitHub’s renderer could affect edge cases. Keep a CI step that validates the rendered output against a reference HTML snapshot.
• MultiMarkdown’s larger parser footprint may slow down large builds. Use it only when footnotes or bibliography are required; otherwise stick with GFM.

Recommendation

For most engineering documentation hosted on GitHub or GitLab, choose GFM to obtain tables and task lists without sacrificing broad renderer compatibility. Reserve MultiMarkdown when you need footnotes, citations, or metadata blocks and your toolchain (e.g., pandoc, multimarkdown) supports it.