DOCSEARCHbyAlgolia
Submit Docs

CommonMark Specification

repository·master·Indexed 26 days ago

https://github.com/commonmark/commonmark-spec

Formal specification and conformance test cases for CommonMark, a rationalized version of Markdown syntax. Includes tools for running tests via Python, a JavaScript npm package for accessing test data, and utilities for generating HTML and PDF versions of the specification.

Tokens
603
Snippets
3
Records
6
Agent score
40%

What's inside commonmark-spec

  1. Build HTML or PDF versions of the CommonMark spec

    master

    You can generate documentation versions of the spec from the source spec.txt using make.

    Prerequisites

    • Lua and LuaRocks: Required for both formats.
    • lcmark: A Lua rock required for building. Install it via:
      luarocks install lcmark
    • XeLaTeX: Required specifically for building the PDF version.

    Build Commands

    • To build HTML:
      make spec.html
    • To build PDF:
      make spec.pdf
    luarocks install lcmark
make spec.html
make spec.pdf

  2. Run conformance tests against the CommonMark spec

    master

    The CommonMark spec contains over 500 embedded examples used as conformance tests. You can run these tests against a specific program (e.g., a Markdown parser) using the provided Python script.

    To run tests against an executable $PROG:

    python3 test/spec_tests.py --program $PROG

    To extract the raw test data as JSON without executing the tests:

    python3 test/spec_tests.py --dump-tests
    python3 test/spec_tests.py --program $PROG

  3. Use the commonmark-spec npm package for JavaScript tests

    master

    JavaScript developers can use the commonmark-spec npm package to access the spec's test data. The package exports a tests array containing JSON objects. Each object represents a test case with the following structure:

    • markdown: The input Markdown source.
    • html: The expected HTML output.
    • section: The name of the spec section.
    • number: The test case number.
    {
  "markdown": "Foo\nBar\n---\n",
  "html": "<h2>Foo\nBar</h2>\n",
  "section": "Setext headings",
  "number": 65
}

  4. Access CommonMark conformance test data

    master
    The commonmark-spec package exports the full CommonMark specification text and a structured array of conformance tests. You can use these to verify if a Markdown parser correctly implements the CommonMark specification by comparing its output against the provided markdown and html pairs.

  5. Use the exported tests array for conformance testing

    master

    The tests property is an array of objects. Each object represents a specific test case extracted from the specification and contains the following fields:

    • markdown: The input Markdown string.
    • html: The expected HTML output string.
    • section: The heading/section name from the spec where the test resides.
    • number: An incremental integer identifying the test case.