{"id":15306,"library":"commonmark-spec","title":"CommonMark Specification and Test Cases","description":"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.","status":"active","version":"0.31.2","language":"javascript","source_language":"en","source_url":"https://github.com/commonmark/CommonMark","tags":["javascript","commonmark","markdown"],"install":[{"cmd":"npm install commonmark-spec","lang":"bash","label":"npm"},{"cmd":"yarn add commonmark-spec","lang":"bash","label":"yarn"},{"cmd":"pnpm add commonmark-spec","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a named array `tests` containing JSON objects, each representing a CommonMark test case. ESM import is standard.","wrong":"const tests = require('commonmark-spec');","symbol":"tests","correct":"import { tests } from 'commonmark-spec';"},{"note":"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.","wrong":"import { spec } from 'commonmark-spec';","symbol":"spec","correct":"import spec from 'commonmark-spec/spec.txt?raw';"},{"note":"Type definition for individual test objects. Path might vary based on package structure and TypeScript configuration.","symbol":"CommonMarkTest","correct":"import type { CommonMarkTest } from 'commonmark-spec/dist/types';"}],"quickstart":{"code":"import { tests } from 'commonmark-spec';\n\nconsole.log(`Total CommonMark test cases: ${tests.length}`);\n\n// Display the first few test cases\nfor (let i = 0; i < Math.min(3, tests.length); i++) {\n  const test = tests[i];\n  console.log(`\\n--- Test Case ${test.number} (${test.section}) ---\\n`);\n  console.log('Markdown Input:\\n' + test.markdown.trim());\n  console.log('Expected HTML Output:\\n' + test.html.trim());\n}\n\n// Example of how to filter tests for a specific section\nconst emphasisTests = tests.filter(test => test.section === 'Emphasis and strong emphasis');\nconsole.log(`\\nNumber of emphasis tests: ${emphasisTests.length}`);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":"<0.24"},{"fix":"Review the CC-BY-SA 4.0 license terms and ensure compliance for your project, especially regarding attribution and share-alike conditions.","message":"Starting 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.","severity":"breaking","affected_versions":">=0.31.0"},{"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.","message":"Terminology 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).","severity":"gotcha","affected_versions":">=0.23"},{"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')`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot destructure property 'tests' of 'commonmark-spec' as it is undefined."},{"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.","cause":"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.","error":"Cannot read properties of undefined (reading 'markdown')"}],"ecosystem":"npm"}