CommonMark is a formally specified, unambiguous standard for core Markdown parsing. It was created to solve a fundamental problem with the original 2004 Markdown specification: John Gruber's definition left many edge cases undefined, which meant different tools produced different results from identical source text. CommonMark resolves this with a complete, testable specification — if a tool claims CommonMark compliance, your Markdown will parse and render predictably.
Today CommonMark is the foundation most modern Markdown tools build on. GitHub, GitLab, VS Code, Discourse, and many static site generators all use CommonMark as their base layer, sometimes with extensions added on top.
Best Practice
- Write to CommonMark when portability is your priority — documents that follow the spec render consistently across all compliant tools, with no surprises.
- Avoid features outside the CommonMark spec (such as tables or footnotes) if you need the file to display correctly in every CommonMark renderer without additional configuration.
- CommonMark is the right choice for README files, wiki pages, and any document shared across tools and platforms.
Notes
Origin
John Gruber and Aaron Swartz published the original Markdown specification in 2004, alongside a Perl conversion script. The spec was intentionally informal — it described the most common cases but left many parsing edge cases open to interpretation. Over time, dozens of implementations emerged, each handling ambiguous cases differently.
By 2012, this inconsistency had become a serious problem for tool authors. A group of contributors — led by John MacFarlane, the creator of Pandoc — began work on a formal specification. After two years of effort, CommonMark was announced publicly in September 2014.
The spec is maintained at commonmark.org and includes a comprehensive test suite that any compliant implementation must pass.
What CommonMark Defines
CommonMark covers all core Markdown elements:
- ATX and setext headings
- Paragraphs and hard line breaks
- Thematic breaks
- Blockquotes
- Unordered and ordered lists
- Fenced and indented code blocks
- HTML blocks and inline HTML
- Links (inline and reference-style) and images
- Emphasis, strong emphasis, and code spans
- Autolinks
The specification is precise about how each element interacts with others — for example, exactly when a list item ends, or which characters can open and close emphasis.
What CommonMark Does Not Include
CommonMark deliberately covers only the core elements. The following are not part of the spec and require a flavour extension:
- Tables
- Task lists
- Strikethrough
- Footnotes
- Definition lists
- Maths notation
- Mermaid diagrams
- Admonitions and callouts
- Metadata frontmatter
Most CommonMark-based tools add some of these via extensions. GitHub Flavoured Markdown and Pandoc Markdown are both built on CommonMark with extensions layered on top.
Where You Will Encounter CommonMark
CommonMark is the underlying parser in many popular writing and publishing tools:
- GitHub and GitLab — use CommonMark as the base, with GFM extensions added on top
- VS Code — the built-in Markdown preview uses a CommonMark-compliant renderer
- Discourse — the forum platform uses a CommonMark parser
- Docusaurus — the documentation site generator uses CommonMark as its base
- Obsidian — the note-taking app uses a CommonMark-compliant parser with its own extensions
Practical Examples
- A notebook that works everywhere: Writing to the CommonMark spec means your content displays consistently whether you open the file in VS Code, share it on GitHub, or publish it with a static site generator. There are no surprises.
# Sourdough Starter Journal
A simple log of my bread-making experiments.
## Getting Started
Before mixing your first batch, read through the full method below.
## Week One
The starter looked sluggish on day two, but by day four it had doubled in size overnight.
- A shared club newsletter draft: CommonMark's consistent behaviour means everyone editing the file — regardless of which Markdown tool they use — sees the same result.
## Upcoming Events
- **Saturday 14 June** — Summer fair, Memorial Hall
- **Friday 20 June** — Book club: *A Month in the Country*
- **Sunday 29 June** — Sponsored walk, details to follow
> Please confirm your attendance by the Wednesday before each event.
- A recipe with a clear structure: Core CommonMark elements — headings, lists, and emphasis — are all you need for a well-structured recipe page that renders correctly on any platform.
# Lemon and Herb Roasted Chicken
## Ingredients
- 1 whole chicken, approximately 1.5 kg
- 2 lemons, halved
- A small bunch of fresh thyme
- 3 cloves of garlic, crushed
- Olive oil, salt, and black pepper
## Method
1. Preheat the oven to 200 °C.
2. Rub the chicken all over with olive oil and season generously.
3. Stuff the cavity with the lemon halves, thyme, and garlic.
4. Roast for **1 hour 20 minutes**, or until the juices run clear.
Lemon and Herb Roasted Chicken
Ingredients
- 1 whole chicken, approximately 1.5 kg
- 2 lemons, halved
- A small bunch of fresh thyme
- 3 cloves of garlic, crushed
- Olive oil, salt, and black pepper
Method
- Preheat the oven to 200 °C.
- Rub the chicken all over with olive oil and season generously.
- Stuff the cavity with the lemon halves, thyme, and garlic.
- Roast for 1 hour 20 minutes, or until the juices run clear.