CommonMark Guide

Markdown was originally designed to make writing for the web simple, but its original documentation intentionally left some behaviours undefined. As Markdown became widely adopted, different applications implemented their own parsing rules, which meant the same Markdown document could render differently depending on the software being used.

CommonMark was introduced to solve this problem by defining a precise specification for Markdown parsing. Instead of relying on individual parser behaviour, developers can implement a common standard that produces consistent and predictable results.

Today, many modern Markdown parsers either fully support CommonMark or use it as the foundation for their own Markdown implementation, including GitHub Flavored Markdown.

Before CommonMark, there was no universally accepted Markdown specification.

This led to common problems such as:

• The same Markdown document rendering differently across editors.
• Ambiguous parsing rules for nested lists and block elements.
• Inconsistent handling of whitespace and line breaks.
• Different HTML output from different Markdown processors.

CommonMark established a comprehensive specification and test suite so Markdown parsers could behave consistently. Rather than changing the Markdown language itself, it standardises how compliant parsers interpret Markdown documents.

The result is greater compatibility between tools and fewer surprises when moving content between platforms.

Although the terms are often used together, they describe different things.

A useful way to think about it is:

Markdown defines the language. CommonMark defines the standard for implementing that language consistently.

See Markdown Syntax for the full set of formatting rules CommonMark standardizes.

If you only write Markdown in a single application, parser differences may never become noticeable.

However, consistency becomes much more important when content is shared across multiple tools or publishing workflows.

CommonMark helps provide predictable rendering for:

• Open-source repositories
• Technical documentation
• Static site generators
• Developer portals
• Knowledge bases
• Collaborative writing projects

Following a common specification makes documentation easier to maintain because contributors can expect the same Markdown to produce the same structure regardless of where it's rendered.

CommonMark is especially valuable for people who create Markdown intended for long-term maintenance or publication.

It is particularly useful for:

• Software developers
• Technical writers
• Documentation teams
• Open-source maintainers
• Documentation platform owners
• Anyone publishing Markdown across multiple tools

For personal notes, parser differences may not matter. For documentation that moves between repositories, editors, and publishing systems, following the CommonMark specification improves consistency and portability. See Markdown Best Practices for related documentation guidelines.

CommonMark and GitHub Flavored Markdown (GFM) are closely related, but they are not the same thing.

CommonMark defines the core specification for Markdown, while GitHub Flavored Markdown builds on that specification by adding features designed for collaborative software development and documentation.

Many developers use GFM every day without realising that it extends CommonMark rather than replacing it.

Some examples of GitHub-specific extensions include:

• Tables
• Task lists
• Strikethrough
• Automatic URL linking
• Alerts (supported in GitHub documentation)

If you're writing documentation that may be published on different platforms, sticking to CommonMark-compatible syntax generally provides the best portability. See GitHub Markdown for README-specific workflows.

Not every Markdown editor or parser behaves exactly the same.

Some applications fully implement the CommonMark specification, while others add their own extensions or support only part of the standard.

When choosing a Markdown tool, it's useful to know whether it:

• Supports the CommonMark specification.
• Adds platform-specific extensions.
• Changes rendering behaviour for certain elements.
• Allows CommonMark-compliant output.

If portability matters, look for tools that clearly document their CommonMark support.

Many modern Markdown tools are built around CommonMark or use it as their parsing foundation.

You'll commonly encounter CommonMark in:

• Documentation platforms
• Static site generators
• Markdown parsers
• Developer documentation
• Publishing workflows
• Knowledge management systems

Some platforms extend CommonMark with additional features, but the underlying specification often remains the starting point.

One of CommonMark's biggest advantages is portability.

If your documents will be shared across multiple editors or publishing systems, following a few simple practices can help avoid rendering differences.

Prefer Standard Syntax#

Use Markdown features defined by the CommonMark specification whenever possible.

Platform-specific extensions may not render correctly everywhere.

Avoid Unnecessary Extensions#

Features such as tables, task lists, or custom callouts may depend on the parser being used.

If maximum compatibility is your goal, verify that the destination platform supports those extensions.

Test Important Documents#

Before publishing documentation or migrating content, preview it in the target platform.

Small differences in rendering are easier to fix before publication than after deployment. Use the Markdown Editor to preview your Markdown before publishing.

Keep Formatting Consistent#

Use clear heading levels, consistent list indentation, and predictable spacing.

Well-structured Markdown is generally easier for both people and parsers to interpret. See Markdown Style Guide for formal formatting standards.

Assuming Every Markdown Parser Behaves the Same#

Different Markdown implementations may interpret edge cases differently.

Following the CommonMark specification reduces this risk, but not every application fully implements it.

Relying on Platform-Specific Features#

Features available on one platform may not exist on another.

If portability is important, avoid depending on extensions unless you know they're supported where the document will be used.

Confusing CommonMark with GitHub Flavored Markdown#

CommonMark is the specification.

GitHub Flavored Markdown is an implementation that extends the specification with additional features.

Understanding this distinction helps you choose the right syntax for your workflow.

Ignoring Documentation Standards#

For team documentation, agreeing on a consistent Markdown standard helps reduce formatting issues and makes collaboration easier.

The easiest way to understand CommonMark is to write a document using only standard, spec-compliant syntax and preview it.

Open the Markdown Editor and try writing a short document using headings, lists, links, and code blocks — all features defined by the CommonMark specification. Keep the Markdown Cheat Sheet open for quick syntax lookup.

Summary#

CommonMark is a formal specification that standardizes how Markdown should be parsed and rendered, eliminating the inconsistencies found in early Markdown implementations.

In this guide, you learned:

• What CommonMark is and why it was created
• How CommonMark differs from Markdown
• How CommonMark relates to GitHub Flavored Markdown (GFM)
• What CommonMark compliance means for Markdown tools
• Where CommonMark is commonly used
• How to write portable, standards-compliant Markdown

Whether you're maintaining open-source documentation, building a documentation platform, or writing Markdown that needs to move between tools, understanding CommonMark helps you produce content that renders consistently everywhere.