{"id":15632722,"url":"https://github.com/widdershin/markdown-doctest","last_synced_at":"2025-04-12T23:29:51.806Z","repository":{"id":60883964,"uuid":"44947201","full_name":"Widdershin/markdown-doctest","owner":"Widdershin","description":"Test all the code in your markdown docs!","archived":false,"fork":false,"pushed_at":"2020-10-07T04:06:36.000Z","size":481,"stargazers_count":167,"open_issues_count":13,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T02:09:28.802Z","etag":null,"topics":["docs","markdown","markdown-doctest","testing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Widdershin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-26T05:06:13.000Z","updated_at":"2024-12-12T15:54:41.000Z","dependencies_parsed_at":"2022-10-06T09:33:41.494Z","dependency_job_id":null,"html_url":"https://github.com/Widdershin/markdown-doctest","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widdershin%2Fmarkdown-doctest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widdershin%2Fmarkdown-doctest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widdershin%2Fmarkdown-doctest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Widdershin%2Fmarkdown-doctest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Widdershin","download_url":"https://codeload.github.com/Widdershin/markdown-doctest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647196,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","markdown","markdown-doctest","testing"],"created_at":"2024-10-03T10:45:07.296Z","updated_at":"2025-04-12T23:29:51.778Z","avatar_url":"https://github.com/Widdershin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/markdown-doctest.svg)](http://badge.fury.io/js/markdown-doctest)\n[![Build Status](https://travis-ci.org/Widdershin/markdown-doctest.svg?branch=master)](https://travis-ci.org/Widdershin/markdown-doctest)\n[![Greenkeeper badge](https://badges.greenkeeper.io/Widdershin/markdown-doctest.svg)](https://greenkeeper.io/)\n\n* * *\n\n# markdown-doctest\n\nTest all the code in your markdown docs!\n\nWhy on earth?\n---\n\nAs an open source developer, there are few things more embarrassing than a user opening an issue to inform you that your README example is broken! With  `markdown-doctest`, you can rest easy knowing that your example code is *actually runnable*.\n\nInstallation\n---\nJust `npm install markdown-doctest` and run `markdown-doctest`. It will run all of the Javascript code examples tucked away in your markdown, and let you know if any blow up.\n\nOkay, how do I use it?\n---\n\nLet's try it on this repo!\n\n```js\nvar a = 5;\n\nvar b = 10;\n\nconsole.log(a + c);\n```\n\nThere's a problem with that example. `markdown-doctest` finds it for us:\n\n```bash\n$ markdown-doctest\nx..\n\nFailed - README.md:32:17\nevalmachine.\u003canonymous\u003e:7\nconsole.log(a + c);\n                ^\n\nReferenceError: c is not defined\n```\n\nAwesome! No excuse for broken documentation ever again, right? :wink:\n\nWe can also run specific files or folders by running `markdown-doctest` with a glob, like `markdown-doctest docs/**/*.md`. By default `markdown-doctest` will recursively run all the `.md` or `.markdown` files starting with the current directory, with the exception of the `node_modules` directory.\n\nNote: `markdown-doctest` doesn't actually attempt to provide any guarantee that your code worked, only that it didn't explode in a horrible fashion. If you would like to use `markdown-doctest` for actually testing the correctness of your code, you can add some `assert`s to your examples.\n\n`markdown-doctest` is not a replacement for your test suite. It's designed to run with your CI build and give you peace of mind that all of your examples are at least vaguely runnable.\n\nSo how do I write those examples?\n---\n\nIn your markdown files, anything inside of code blocks with 'js' or 'es6' will be run. E.g:\n\n    ```js\n    console.log(\"Yay, tests in my docs\");\n    ```\n\n    ```es6\n    const a = 5;\n    console.log({a, foo: 'test'});\n    ```\n\nI have a code example I don't want tested!\n---\nYou can tell `markdown-doctest` to skip examples by adding `\u003c!-- skip-example --\u003e` before the example. E.g:\n\n    \u003c!-- skip-example --\u003e\n    ```js\n    // not a runnable example\n\n    var foo = download(...);\n    ```\n\nHow do requires work? And other setup logic?\n---\n\nYou can `require` any needed modules or example helpers in `.markdown-doctest-setup.js`. E.g:\n\n\u003c!-- skip-example --\u003e\n```js\n// .markdown-doctest-setup.js\nmodule.exports = {\n  require: {\n    Rx: require('rx')\n  },\n\n  globals: {\n    $: require('jquery')\n  }\n}\n```\n\nAnything exported under `require` will then be used by any examples that `require` that key.\nYou must explicitly configure all of the dependencies used in your examples.\n\nAnything exported under `globals` will be available globally across all examples.\n\nYou can also specify a regexRequire section to handle anything more complex than an exact string match!\n\n\u003c!-- skip-example --\u003e\n```js\n// .markdown-doctest-setup.js\nmodule.exports = {\n  require: {\n    Rx: require('rx')\n  },\n\n  regexRequire: {\n    'rx/(.*)': function (fullPath, matchedModuleName) {\n      return require('./dist/' + matchedModuleName);\n    }\n  }\n}\n```\n\nDo I have to enable es6 support?\n---\n\nNope, ES6 support is on by default. You can disable `babel` support\nin your `.markdown-doctest-setup.js` file.\nThis will speed things up drastically:\n\n\u003c!-- skip-example --\u003e\n```js\n//.markdown-doctest-setup.js\nmodule.exports = {\n  babel: false\n}\n```\n\nWhat if I have global state that needs to be reset after my examples run?\n---\n\u003c!-- skip-example --\u003e\n```js\n//.markdown-doctest-setup.js\nmodule.exports = {\n  beforeEach: function () {\n    // reset your awesome global state\n  }\n}\n```\n\nYou can specify a function to be run before each example in your `.markdown-doctest-setup.js`.\n\nWhat if I want to remove custom syntax from examples before processing?\n---\n\n\u003c!-- skip-example --\u003e\n```js\n//.markdown-doctest-setup.js\nmodule.exports = {\n  transformCode(code) {\n    // Remove ... from code syntax\n    return code.replace(/\\.\\.\\./g, \"\");\n  }\n}\n```\n\nWho uses markdown-doctest?\n---\n\nAll of these projects either run `markdown-doctest` with `npm test` or as part of their CI process:\n\n* [lodash](https://github.com/lodash/lodash)\n* [Moment](https://github.com/moment/momentjs.com)\n* [RxJS](https://github.com/ReactiveX/RxJS)\n* [most](https://github.com/cujojs/most)\n* [xstream](https://github.com/staltz/xstream)\n* [cyclejs/time](https://github.com/cyclejs/time)\n* [rx.schedulers](https://github.com/Reactive-Extensions/rx.schedulers)\n* [rx.priorityqueue](https://github.com/Reactive-Extensions/rx.priorityqueue)\n* [rx.disposables](https://github.com/Reactive-Extensions/rx.disposables)\n* [rx-undoable](https://github.com/Widdershin/rx-undoable)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiddershin%2Fmarkdown-doctest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiddershin%2Fmarkdown-doctest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiddershin%2Fmarkdown-doctest/lists"}