How do I test my Markdown parser against CommonMark?

Use the provided test suite by running `python3 test/spec_tests.py --program $PROG` or install the npm package `commonmark-spec` for JavaScript. This validates conformance with over 500 embedded examples from the spec.

What's the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is a formal spec focusing on core Markdown syntax, while GitHub Flavored Markdown (GFM) extends it with features like tables and task lists. GFM is based on CommonMark but adds GitHub-specific extensions for richer content.

Is CommonMark backward compatible with original Markdown?

Yes, it's designed to render most existing Markdown documents as intended, with only a few documented differences like allowing all punctuation to be escaped and adding backslash line breaks to improve predictability.

How can I implement CommonMark in my project?

Start by using one of the reference implementations in C or JavaScript, or choose from third-party libraries in various languages listed on the wiki. Integrate the parser and test against the spec suite for compliance.

Can I extend CommonMark with my own syntax?

While possible, extending CommonMark may break spec compliance. The project focuses on core stability first, so custom extensions should be handled carefully, often requiring forking or a layered approach outside the spec.

CommonMark or Pandoc for document conversion?

CommonMark is a spec for Markdown syntax, ensuring predictable parsing, while Pandoc is a tool that supports multiple formats including CommonMark. Use CommonMark for standardization; use Pandoc for flexible conversion between various markup formats.

Open-Awesome

CommonMark

NOASSERTIONPython0.31.2

A formal specification for Markdown syntax with reference implementations in C and JavaScript.

Visit Website GitHub

5.1k stars350 forks0 contributors

What is CommonMark?

CommonMark is a formal specification that defines a standardized version of Markdown syntax. It solves the problem of inconsistent and ambiguous Markdown implementations by providing a clear, testable standard that ensures documents render the same way across different platforms and tools.

Target Audience

Developers building Markdown parsers, editors, or documentation tools, as well as technical writers and organizations needing reliable, predictable Markdown rendering.

Value Proposition

It offers a rigorously defined, community-driven standard with reference implementations and a comprehensive test suite, eliminating the guesswork and fragmentation of traditional Markdown.

Overview

CommonMark spec, with reference implementations in C and JavaScript

Use Cases

Best For

Building Markdown parsers that need to be spec-compliant
Ensuring consistent Markdown rendering across different platforms
Creating documentation tools with predictable formatting
Testing Markdown implementations against a standard test suite
Adopting a future-proof, unambiguous Markdown standard
Developing editors or previewers that require reliable syntax handling

Not Ideal For

Projects needing immediate support for extended Markdown features like footnotes, tables, or definition lists
Teams using Markdown for casual, internal docs where strict cross-platform consistency isn't critical
Developers wanting a lightweight, informal parser without spec compliance overhead

Pros & Cons

Pros

Unambiguous Specification

Provides a human-readable spec that precisely defines Markdown syntax, eliminating the guesswork and inconsistencies of original Markdown, as detailed in spec.txt.

Reference Implementations

Offers BSD-licensed parsers in C and JavaScript that strictly adhere to the spec, giving developers reliable starting points for integration.

Comprehensive Test Suite

Includes over 500 embedded examples in the spec that serve as conformance tests, making it easy to validate parser implementations against a standard.

Backward Compatibility

Designed to render most existing Markdown documents as intended, with minimal breaking changes, as explained in the differences section.

Enhanced Syntax Predictability

Rationalizes rules for links, HTML blocks, and lists to improve consistency, addressing common pitfalls in other implementations.

Cons

Limited Core Feature Set

Deliberately excludes popular extensions like footnotes and definition lists to focus on core syntax, which may require additional work for full-featured applications.

Complex Spec Toolchain

Building the spec into HTML or PDF requires installing lua and xelatex, adding setup overhead for contributors or those generating documentation.

Rigidity for Customization

The strict spec can make it challenging to add custom syntax or extensions without breaking compliance, limiting flexibility for niche use cases.

Frequently Asked Questions

Related Projects

Capstone

Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.

Stars8,680

Forks1,670

Last commit2 days ago

libimobiledevice

A cross-platform protocol library to communicate with iOS devices

Stars7,871

Forks1,492

Last commit4 months ago

libffi

A portable foreign-function interface library.

Stars4,229

Forks806

Last commit3 days ago

cpu_features

A cross platform C99 library to get cpu features at runtime.

Stars2,592

Forks295

Last commit16 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub