CommonMark is a specification for Markdown syntax with reference implementations in C and JavaScript.
The original Markdown specification left many aspects of syntax undetermined, leading to incompatible implementations across different tools. CommonMark addresses this by providing a precise, declarative specification that describes what constitutes each structural element—block quotes, code blocks, lists, and others—without prescribing a particular parsing algorithm. The specification is written from the perspective of a human writer rather than as a computer program, and it makes explicit decisions about ambiguous cases by appealing to existing conventions and principles of simplicity, readability, and consistency. The goal is to ensure that documents written for one Markdown implementation render as their authors intended across different tools.
Developers should adopt CommonMark if they need a stable, well-defined standard for Markdown parsing rather than relying on implementation-specific behavior. The specification suits projects that require interoperability across multiple Markdown processors or that need to build new implementations with confidence in their correctness. The repository itself contains the specification source, over 500 embedded conformance test examples, and tooling to validate implementations against the spec. Reference implementations are maintained separately in dedicated repositories, and third-party libraries implementing CommonMark exist across numerous programming languages.
The project maintains the specification as a declarative document in plain text form, with tooling to extract test cases in JSON format and to generate HTML and PDF versions. The specification deliberately limits itself to core Markdown elements described in the original syntax, including visible line break syntax and fenced code blocks, while excluding extensions like footnotes and definition lists. The repository provides Python-based test infrastructure that allows any executable to be validated against the full test suite, and JavaScript developers can access the test data through an npm package published from the repository.
