TopolearnThe same file renders differently across GitHub, docs sites and editors, and tooling catches the differences.
Original Markdown (2004) was loosely specified, and implementations disagreed. CommonMark is the precise specification most modern parsers follow; GFM is CommonMark plus tables, task lists, strikethrough, extended autolinks and HTML tag filtering. Other dialects add their own features: Pandoc Markdown (citations, definition lists), MultiMarkdown, Obsidian (wiki links [[note]]), MkDocs/Python-Markdown (admonitions !!! note, which aren't CommonMark-compliant in all details).
Common add-ons in docs systems:
- Front matter: a YAML block between
---lines at the very top of the file, holding metadata (title, date, tags) for Jekyll, Hugo, Docusaurus, Astro and others. GitHub shows it as a table; a plain CommonMark parser would render it as a rule and a heading. - Diagrams: fenced blocks with
mermaidrender as diagrams on GitHub, GitLab and many doc sites. - Math:
$...$and$$...$$(GitHub, GitLab, many sites) rendered with MathJax or KaTeX. - MDX: Markdown plus JSX components, used by Docusaurus and Next.js; stricter than Markdown (for example,
<and{must be escaped).
Tooling:
- markdownlint (
markdownlint-cli2) enforces consistent style: heading levels, list markers, blank lines around blocks, line length. - Prettier formats Markdown: normalises lists, emphasis markers and table alignment.
- Link checkers (
lychee,markdown-link-check) catch broken links in CI.
Example
---
title: Deploying the API
tags: [ops, kubernetes]
---
# Deploying the API
```mermaid
flowchart LR
dev[Push to main] --> ci[CI tests] --> deploy[Deploy to staging]
```
The cost is $O(n \log n)$ in the worst case.
<!-- .markdownlint.jsonc
{ "MD013": { "line_length": 100 }, "MD004": { "style": "dash" } }
$ npx markdownlint-cli2 "**/*.md"
$ npx prettier --write "**/*.md"
-->Remember
- CommonMark is the spec; GFM adds tables, task lists and strikethrough
- Front matter, mermaid diagrams and $math$ are widespread add-ons
- markdownlint, Prettier and link checkers keep docs consistent in CI
Watch out for
- Using a docs-site-only syntax (admonitions, wiki links) in a README that GitHub renders as plain text.