commonmark-spec

library0.31.2jsnpmunverified

The `commonmark-spec` package provides the official CommonMark specification (`spec.txt`) and a comprehensive suite of over 500 conformance test cases in a machine-readable JSON format. It is a crucial resource for developers building or testing Markdown parsers and renderers that aim for CommonMark compatibility. This package primarily serves as a data source, not a Markdown processor itself; for implementations, refer to `commonmark.js` (JavaScript) or `cmark` (C). The current stable version is 0.31.2, released January 28, 2024. Releases generally occur with updates to the CommonMark specification, which includes clarifications, corrections, and sometimes minor syntactic adjustments. The package's core differentiator is its direct provision of the authoritative spec and its associated, extensive test suite, making it the definitive reference for CommonMark conformance testing.

testing serialization

npm install commonmark-spec

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COMMONMARK-SPEC

commonmark-spec

testingjavascriptv0.31.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tests

✓ import { tests } from 'commonmark-spec';

✗ const tests = require('commonmark-spec');

The primary export is a named array `tests` containing JSON objects, each representing a CommonMark test case. ESM import is standard.

spec

✓ import spec from 'commonmark-spec/spec.txt?raw';

✗ import { spec } from 'commonmark-spec';

The raw `spec.txt` file is not a direct named export. It typically needs to be imported using a bundler-specific raw loader (e.g., Webpack's `raw-loader`, Vite's `?raw` suffix) if you need the raw text content.

CommonMarkTest

✓ import type { CommonMarkTest } from 'commonmark-spec/dist/types';

Type definition for individual test objects. Path might vary based on package structure and TypeScript configuration.

Demonstrates importing the `tests` array and iterating through the first few CommonMark test cases to inspect their structure and content. It also shows filtering tests by section.

import { tests } from 'commonmark-spec'; console.log(`Total CommonMark test cases: ${tests.length}`); // Display the first few test cases for (let i = 0; i < Math.min(3, tests.length); i++) { const test = tests[i]; console.log(`\n--- Test Case ${test.number} (${test.section}) ---\n`); console.log('Markdown Input:\n' + test.markdown.trim()); console.log('Expected HTML Output:\n' + test.html.trim()); } // Example of how to filter tests for a specific section const emphasisTests = tests.filter(test => test.section === 'Emphasis and strong emphasis'); console.log(`\nNumber of emphasis tests: ${emphasisTests.length}`);

Debug

Known issues

breakingThe format for embedded spec examples within `spec.txt` significantly changed in version 0.24. This affects users who directly parse `spec.txt` or use `spec_tests.py --dump-tests` from older versions, as the delimiters and overall structure for examples were revised. The `tests` array exported by the npm package, however, consistently uses the new JSON structure as shown in the README, so direct consumers of the `tests` array were primarily impacted by the *content* changes reflecting the new spec.

fix

If directly parsing `spec.txt`, update parsers to handle the new `example` block format introduced in 0.24. If using `spec_tests.py --dump-tests`, ensure your tooling expects the post-0.24 JSON structure. For `commonmark-spec` npm package users, ensure code correctly handles the `tests` array's JSON structure, especially when comparing against older data sets.

affects: <0.24

breakingStarting with version 0.31.0, the `commonmark-spec` npm package (and the CommonMark spec itself) was relicensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA 4.0). Previous versions used a BSD license. This is a significant legal change that may require review for projects integrating this package.

fix

Review the CC-BY-SA 4.0 license terms and ensure compliance for your project, especially regarding attribution and share-alike conditions.

affects: >=0.31.0

gotchaTerminology within the CommonMark specification has evolved. For example, 'horizontal rule' was renamed to 'thematic break' and 'header' to 'heading' in version 0.23. While this package primarily provides the spec and tests, these changes affect how properties or sections might be named or referenced within the `tests` array (e.g., `section` property in test objects).

fix

When programmatically accessing or filtering test cases, be aware of updated terminology in `section` names and other descriptive fields. Consult the `spec.txt` or the latest version of the tests for current naming conventions.

affects: >=0.23

gotchaThe `commonmark-spec` package exports the `tests` array directly from its main entry point, and the raw `spec.txt` file is not a direct named export. Attempting `import { spec } from 'commonmark-spec'` will fail. To access `spec.txt` content, a bundler-specific raw loader or direct file system access (in Node.js) is typically required.

fix

To import the raw `spec.txt` file in a web project, use a bundler-specific mechanism (e.g., `import specText from 'commonmark-spec/spec.txt?raw';` for Vite/Rollup). In Node.js, use `fs.readFileSync(require.resolve('commonmark-spec/spec.txt'), 'utf8')`.

affects: All versions

Errors

Common errors & fixes

TypeError: Cannot destructure property 'tests' of 'commonmark-spec' as it is undefined.

Attempting to use `require('commonmark-spec')` with ES module destructuring syntax in a CommonJS environment, or in an environment where the package is treated as a default export rather than a named export.

fix

Use `const { tests } = require('commonmark-spec');` for CommonJS environments, or `import { tests } from 'commonmark-spec';` for ES Modules. Ensure your build configuration correctly handles ES modules if mixing syntax.

Cannot read properties of undefined (reading 'markdown')

Accessing `tests[i].markdown` or similar where `tests[i]` might be `undefined` or the structure of a specific test object is unexpected, possibly due to filtering or out-of-bounds access.

fix

Always add checks for array bounds (`i < tests.length`) and object property existence (e.g., `if (test && test.markdown)`) before accessing properties, especially if working with filtered or externally sourced test data.

Upgrade

Version history

0.31.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/commonmark/CommonMark ↗

packagehttps://www.npmjs.com/package/commonmark-spec ↗

homepagehttps://commonmark.org ↗