Markdown Doctest

1.1.0 verified Thu Apr 23 auth: no javascript

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.

Common errors

error ReferenceError: <variable> is not defined ↓

cause 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 Error: Cannot find module '<module-name>' ↓

cause 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 Error loading .markdown-doctest-setup.js: <syntax error details> ↓

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

Warnings

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

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

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

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

Install

npm install markdown-doctest

yarn add markdown-doctest

pnpm add markdown-doctest

Imports

CLI Execution
wrong
```
node markdown-doctest
```
correct
```
npx markdown-doctest [glob]
```
The primary interaction is via the command-line interface. `npx` is recommended for running local installations.
.markdown-doctest-setup.js
wrong
```
export default { /* config object */ };
```
correct
```
module.exports = { /* 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.

Quickstart

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