{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"introduction","path":"/introduction","type":"module","module":"introduction","title":"Why doc-kit","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"doc-kit is a documentation toolkit for APIs. It reads your API from Markdown,\nMDX, TypeScript and JSDoc, and turns it into documentation: a website with\nsearch, JSON described by a schema, `llms.txt` for language models, man pages,\nand any other format a generator can write.\n\nIt's the toolkit behind the [Node.js API reference](https://nodejs.org/api),\nwhich taught it most of what it knows. This page explains what sets it apart,\nand when another tool may suit you better.","summary":"doc-kit is a documentation toolkit for APIs. It reads your API from Markdown, MDX, TypeScript and JSDoc, and turns it into documentation: a website with search, JSON described by a schema, `llms.txt` for language models, man pages, and any other format a generator can write.","examples":[],"children":[{"kind":"section","id":"built-around-the-api","name":"Built around the API","title":"Built around the API","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Most documentation tools see a page. doc-kit also sees the API in it. A\nheading like `server.listen(port[, callback])` is a method with its signature,\nthe list under it holds its typed parameters, a YAML comment holds its\nhistory, and a `Stability:` blockquote says where it is in its lifecycle. That\nstructure is part of [doc-kit's Markdown specification](./specification.html),\nso every output gets it as data, not as text that happens to look like an\nAPI:\n\n* types in braces link to their documentation: on your site, on MDN, or\n  wherever your type map points;\n* pages show each entry's history, stability and source;\n* the JSON output carries all of it, described by a published schema.\n\nTypeScript projects can skip most of the writing: the experimental\n[`@doc-kit/typedoc`](./packages/typedoc.html) plugin for TypeDoc turns their\nsource and its JSDoc comments into the same Markdown. See\n[Documenting TypeScript](./typescript.html).","summary":"Most documentation tools see a page. doc-kit also sees the API in it. A heading like `server.listen(port[, callback])` is a method with its signature, the list under it holds its typed parameters, a YAML comment holds its history, and a `Stability:` blockquote says where it is in its lifecycle. That structure is part of doc-kit's Markdown specification, so every output gets it as data, not as text that happens to look like an API:","examples":[],"children":[]},{"kind":"section","id":"one-parse-every-output","name":"One parse, every output","title":"One parse, every output","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each output comes from a [generator](./generators.html): a module that names the\ngenerator it reads from and writes its own format. doc-kit loads the generators\na build asks for, along with the ones they read from, wires them into a graph,\nparses your sources once, and runs the generators that don't depend on one\nanother at the same time.\n\nA format of your own, such as an RSS feed, a changelog or TypeScript\ndeclarations, is one more module reading the same typed API entries as the\nwebsite. You pass its path to `--target` like any built-in name. See\n[Creating generators](./creating-generators.html).","summary":"Each output comes from a generator: a module that names the generator it reads from and writes its own format. doc-kit loads the generators a build asks for, along with the ones they read from, wires them into a graph, parses your sources once, and runs the generators that don't depend on one another at the same time.","examples":[],"children":[]},{"kind":"section","id":"performance","name":"Performance","title":"Performance","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The heavy stages, from parsing Markdown to rendering the website, split their\nwork into chunks and run them on worker threads: one per CPU core, up to four,\nunless you set [`--threads`](./cli.html).\n\nMemory stays low too. Each stage's result is dropped as soon as the last\ngenerator reading it is done with it, and the website generator holds one page\nper worker, so its memory follows your largest page rather than the size of\nthe whole site.\n\nBuilding this site, 34 pages and 48,316 words, with its own\n[configuration](https://github.com/nodejs/doc-kit/blob/main/www/doc-kit.config.mjs)\n(medians of five clean builds):\n\n| Targets                         | Output                                | Time   |\n| ------------------------------- | ------------------------------------- | ------ |\n| `llms-txt`                      | `llms.txt`                            | 0.53 s |\n| `orama-db`                      | The search index                      | 0.55 s |\n| `json`                          | 34 JSON documents                     | 0.58 s |\n| `html`                          | The site: 34 pages, bundled with Vite | 2.81 s |\n| The configuration's six targets | All of it, 199 files                  | 3.0 s  |\n\nMost of the website's time is Vite bundling its scripts and styles once, a\ncost that doesn't grow with the number of pages. The Node.js API reference\nshows how the rest scales, with 70 files and 574,627 words:\n\n| Targets                                         | Output               | Time   |\n| ----------------------------------------------- | -------------------- | ------ |\n| `llms-txt`                                      | `llms.txt`           | 2.1 s  |\n| `orama-db`                                      | The search index     | 2.5 s  |\n| `json`                                          | 70 JSON documents    | 2.5 s  |\n| `section-pages`                                 | The site: 781 pages  | 8.8 s  |\n| `section-pages`, `json`, `llms-txt`, `orama-db` | All of it, 923 files | 10.1 s |\n\nClean builds, median of three, on an AMD Ryzen 9 8945HX (16 cores) with\nNode.js 24.18 and doc-kit `ec7751f`, using the configuration of\n[the Node.js preview site](https://beta.docs.nodejs.org/). To reproduce them,\nrun this from a doc-kit checkout with its dependencies installed:\n\n```bash\ngit clone --depth 1 --branch v26.12.1 https://github.com/nodejs/node.git node\nnode packages/cli/bin/cli.mjs generate \\\n  -t section-pages -t json -t llms-txt -t orama-db \\\n  -i \"node/doc/api/*.md\" --ignore node/doc/api/quic.md \\\n  --type-map node/doc/type-map.json -c node/CHANGELOG.md \\\n  -v v26.12.1 --config-file beta/doc-kit.config.mjs -o out\n```","summary":"The heavy stages, from parsing Markdown to rendering the website, split their work into chunks and run them on worker threads: one per CPU core, up to four, unless you set `--threads`.","examples":[{"language":"bash","displayName":null,"code":"git clone --depth 1 --branch v26.12.1 https://github.com/nodejs/node.git node\nnode packages/cli/bin/cli.mjs generate \\\n  -t section-pages -t json -t llms-txt -t orama-db \\\n  -i \"node/doc/api/*.md\" --ignore node/doc/api/quic.md \\\n  --type-map node/doc/type-map.json -c node/CHANGELOG.md \\\n  -v v26.12.1 --config-file beta/doc-kit.config.mjs -o out"}],"children":[]},{"kind":"section","id":"light-by-default","name":"Light by default","title":"Light by default","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The [website generator](./generators/html.html) renders every page to static\nHTML at build time, and the content is never shipped as JavaScript. Only the\ninteractive parts load code, as islands: the search box, the theme switch, the\nsidebar and announcement banners hydrate once the browser is idle, and a code\nblock hydrates the first time you point at, focus or touch it, for its copy\nbutton and tabs.\n\nIn browsers with the Navigation API, following a link to another page of the\nsite swaps it in place, without a full reload. Pages are prefetched when you\nhover over or press a link, so most navigations don't wait on the network.","summary":"The website generator renders every page to static HTML at build time, and the content is never shipped as JavaScript. Only the interactive parts load code, as islands: the search box, the theme switch, the sidebar and announcement banners hydrate once the browser is idle, and a code block hydrates the first time you point at, focus or touch it, for its copy button and tabs.","examples":[],"children":[]},{"kind":"section","id":"used-by","name":"Used by","title":"Used by","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A few places doc-kit is already in use. Feel free to open a pull request to\nadd yours.\n\n* <https://nodejs.org/api>, the Node.js API reference\n* <https://beta.docs.nodejs.org/>, its next version\n* <https://nodejs.org/learn>, the Node.js guides\n* <https://nodejs.org/llms.txt>\n* <https://webpack-doc-kit.vercel.app/>, a preview of webpack's docs\n* <https://undici.nodejs.org/>, Undici's docs","summary":"A few places doc-kit is already in use. Feel free to open a pull request to add yours.","examples":[],"children":[]},{"kind":"section","id":"when-to-use-something-else","name":"When to use something else","title":"When to use something else","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"doc-kit is made for documenting APIs. If your site is mostly prose, without an\nAPI behind it, a general-purpose site generator such as\n[VitePress](https://vitepress.dev/), [Docusaurus](https://docusaurus.io/) or\n[Eleventy](https://www.11ty.dev/) may suit you better. doc-kit handles guides\nwell too, as this site shows, but they aren't why it exists.\n\nIf your docs have an API behind them, [Getting started](./getting-started.html)\ntakes you from one Markdown file to a site with search in a few minutes.","summary":"doc-kit is made for documenting APIs. If your site is mostly prose, without an API behind it, a general-purpose site generator such as VitePress, Docusaurus or Eleventy may suit you better. doc-kit handles guides well too, as this site shows, but they aren't why it exists.","examples":[],"children":[]},{"kind":"section","id":"get-involved","name":"Get involved","title":"Get involved","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"doc-kit is an open source project of the Node.js organization. Bug reports,\nideas and pull requests are welcome in the [issue tracker](https://github.com/nodejs/doc-kit/issues), and the\n[contributing guide](https://github.com/nodejs/doc-kit/blob/main/CONTRIBUTING.md) explains how to set up the repository. You can find the\nteam in the [#nodejs-website channel](https://openjs-foundation.slack.com/archives/CVAMEJ4UV) on [the OpenJS Slack](http://slack.openjsf.org/).","summary":"doc-kit is an open source project of the Node.js organization. Bug reports, ideas and pull requests are welcome in the issue tracker, and the contributing guide explains how to set up the repository. You can find the team in the #nodejs-website channel on the OpenJS Slack.","examples":[],"children":[]}]}