markdown-doctest

library1.1.0jsnpmunverified

markdown-doctest is a command-line utility designed to automatically test code examples embedded within Markdown documentation files. Its primary purpose is to prevent out-of-date or broken code snippets from appearing in project READMEs and other documentation, thereby improving the user experience and reducing embarrassing issues for open-source maintainers. The current stable version is 1.1.0. The project has seen releases relatively consistently in its past, indicating an active maintenance phase, though a specific release cadence is not strictly defined. It differentiates itself by focusing specifically on validating documentation code for executability rather than correctness (unless assertions are explicitly added), integrating seamlessly into CI/CD pipelines, and offering flexible configuration for requiring modules, defining globals, and ignoring specific examples or file patterns. It's not a replacement for a comprehensive test suite but rather a complementary tool for documentation integrity.

testing

npm install markdown-doctest

github ↗package ↗

INSTALL

IMPORT

SIG · MARKDOWN-DOCTEST

markdown-doctest

testingjavascriptv1.1.0

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.

CLI Execution

✓ npx markdown-doctest [glob]

✗ node markdown-doctest

The primary interaction is via the command-line interface. `npx` is recommended for running local installations.

.markdown-doctest-setup.js

✓ module.exports = { /* config object */ };

✗ export default { /* config object */ };

This configuration file is loaded as CommonJS. It is used to define global variables, required modules for your examples, disable Babel, or set up `beforeEach` hooks.

Skipping Examples

✓  ```js // code to skip ```

Place the HTML comment `` directly before a code block to prevent markdown-doctest from executing it.

Demonstrates installing markdown-doctest, creating a markdown file with both a working and a broken code example, and then running the doctests to show how errors are reported.

mkdir doctest-example cd doctest-example npm init -y npm install markdown-doctest cat > README.md <<EOF # My Awesome Project This is a great project! ## Example Usage ```js const greeting = "Hello"; const name = "World"; console.log(greeting + ", " + name + "!"); ``` ## Broken Example ```js // This will fail const x = 10; console.log(x + y); ``` EOF # Run the doctests npx markdown-doctest # Expected Output (truncated, showing failure) # x. # # Failed - README.md:16:17 # evalmachine.<anonymous>:7 # console.log(x + y); # ^ # # ReferenceError: y is not defined

markdown-doctest --version

Debug

Known issues

breakingThe tool will now return a non-zero exit code if an error is encountered loading the `.markdown-doctest-config.js` or `.markdown-doctest-setup.js` files. This prevents silent failures in CI/CD environments where a broken configuration might previously have gone unnoticed.

fix

Ensure your `.markdown-doctest-setup.js` (and any `.markdown-doctest-config.js` if used) files are syntactically correct and contain valid CommonJS exports.

affects: >=0.6.0

breakingCode snippets with the language specifier `json` will no longer be incorrectly attempted to be run as JavaScript. If you relied on this behavior for any reason, those blocks will now be skipped.

fix

If you need to validate JSON syntax, use a dedicated JSON linter. markdown-doctest focuses on JavaScript/ES6 code execution.

affects: >=0.9.1

breakingThe package upgraded to Babel 6. This change ensures compatibility with newer JavaScript syntax and tooling but might impact projects that were configured for older Babel versions or have specific Babel 5 dependencies.

fix

Review your project's Babel configuration if you encounter unexpected compilation errors. If you don't need Babel, you can explicitly disable it in `.markdown-doctest-setup.js` with `babel: false` for faster execution.

affects: >=0.5.0

gotchaBy default, `markdown-doctest` recursively scans all `.md` or `.markdown` files but automatically ignores `node_modules` directories in all locations, not just the root.

fix

If you explicitly need to test markdown files within a `node_modules` sub-directory (an uncommon use case), you would need to adjust your glob patterns and potentially override default ignore settings, though this is not directly supported via a configuration option for `node_modules` itself.

affects: >=0.3.1

Errors

Common errors & fixes

ReferenceError: <variable> is not defined

A variable used in a code example within a markdown file was not declared or made available to the doctest execution context.

fix

Ensure all variables are declared within the code block, or configure `.markdown-doctest-setup.js` to expose necessary `globals` or `require` common modules for your examples.

Error: Cannot find module '<module-name>'

A `require()` call within a markdown code example failed because the module was not configured in `.markdown-doctest-setup.js`.

fix

Add the required module to the `require` section of your `.markdown-doctest-setup.js` file, e.g., `module.exports = { require: { Rx: require('rx') } }`.

Error loading .markdown-doctest-setup.js: <syntax error details>

The `.markdown-doctest-setup.js` file contains a JavaScript syntax error, making it unparseable by the tool.

fix

Correct the syntax errors in your `.markdown-doctest-setup.js` file. These errors will now cause the test run to halt with a non-zero exit code.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Widdershin/markdown-doctest ↗

packagehttps://www.npmjs.com/package/markdown-doctest ↗