CommonMark Specification and Test Cases

Common errors

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

  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.
  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')

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Review the CC-BY-SA 4.0 license terms and ensure compliance for your project, especially regarding attribution and share-alike conditions.
• gotcha 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).
  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.
• gotcha 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.
  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')`.

Install

• npm install commonmark-spec npm
• yarn add commonmark-spec yarn
• pnpm add commonmark-spec pnpm

Imports

• tests
  wrong:

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

  correct:

  import { tests } from 'commonmark-spec';

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

  import { spec } from 'commonmark-spec';

  correct:

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

  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.

Quickstart

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}`);