{"id":17789,"library":"markdown-doctest","title":"Markdown Doctest","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/Widdershin/markdown-doctest","tags":["javascript","markdown","test","documentation"],"install":[{"cmd":"npm install markdown-doctest","lang":"bash","label":"npm"},{"cmd":"yarn add markdown-doctest","lang":"bash","label":"yarn"},{"cmd":"pnpm add markdown-doctest","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary interaction is via the command-line interface. `npx` is recommended for running local installations.","wrong":"node markdown-doctest","symbol":"CLI Execution","correct":"npx markdown-doctest [glob]"},{"note":"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.","wrong":"export default { /* config object */ };","symbol":".markdown-doctest-setup.js","correct":"module.exports = { /* config object */ };"},{"note":"Place the HTML comment `<!-- skip-example -->` directly before a code block to prevent markdown-doctest from executing it.","symbol":"Skipping Examples","correct":"<!-- skip-example -->\n```js\n// code to skip\n```"}],"quickstart":{"code":"mkdir doctest-example\ncd doctest-example\nnpm init -y\nnpm install markdown-doctest\n\ncat > README.md <<EOF\n# My Awesome Project\n\nThis is a great project!\n\n## Example Usage\n\n```js\nconst greeting = \"Hello\";\nconst name = \"World\";\nconsole.log(greeting + \", \" + name + \"!\");\n```\n\n## Broken Example\n\n```js\n// This will fail\nconst x = 10;\nconsole.log(x + y);\n```\nEOF\n\n# Run the doctests\nnpx markdown-doctest\n\n# Expected Output (truncated, showing failure)\n# x. \n# \n# Failed - README.md:16:17\n# evalmachine.<anonymous>:7\n# console.log(x + y);\n#                 ^\n# \n# ReferenceError: y is not defined","lang":"bash","description":"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."},"warnings":[{"fix":"Ensure your `.markdown-doctest-setup.js` (and any `.markdown-doctest-config.js` if used) files are syntactically correct and contain valid CommonJS exports.","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"If you need to validate JSON syntax, use a dedicated JSON linter. markdown-doctest focuses on JavaScript/ES6 code execution.","message":"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.","severity":"breaking","affected_versions":">=0.9.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"By default, `markdown-doctest` recursively scans all `.md` or `.markdown` files but automatically ignores `node_modules` directories in all locations, not just the root.","severity":"gotcha","affected_versions":">=0.3.1"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"A variable used in a code example within a markdown file was not declared or made available to the doctest execution context.","error":"ReferenceError: <variable> is not defined"},{"fix":"Add the required module to the `require` section of your `.markdown-doctest-setup.js` file, e.g., `module.exports = { require: { Rx: require('rx') } }`.","cause":"A `require()` call within a markdown code example failed because the module was not configured in `.markdown-doctest-setup.js`.","error":"Error: Cannot find module '<module-name>'"},{"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.","cause":"The `.markdown-doctest-setup.js` file contains a JavaScript syntax error, making it unparseable by the tool.","error":"Error loading .markdown-doctest-setup.js: <syntax error details>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}