{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators","path":"/generators","type":"module","module":"generators","title":"Generators","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A generator makes one output from your documentation: the website, the search\nindex, JSON, a man page. You pick generators by their target name with\n`--target` (`-t`) on the [CLI](./cli.html), or with `target` in the\n[configuration file](./configuration.html). However many you pick, doc-kit parses\nyour sources once and every generator reads that result.\n\n```bash\nnpx @doc-kit/cli generate -t html -t orama-db -t sitemap -i \"docs/**/*.md\" -o out\n```\n\n![Generators form a graph through dependsOn; picking html and orama-db runs only them and what they depend on, parsing your sources once](./diagrams/generator-graph.svg)","summary":"A generator makes one output from your documentation: the website, the search index, JSON, a man page. You pick generators by their target name with `--target` (`-t`) on the CLI, or with `target` in the configuration file. However many you pick, doc-kit parses your sources once and every generator reads that result.","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli generate -t html -t orama-db -t sitemap -i \"docs/**/*.md\" -o out"}],"children":[{"kind":"section","id":"the-website","name":"The website","title":"The website","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From [`@doc-kit/generator-react`](./packages/react.html), which you install next\nto the CLI.\n\n| Generator                                        | Target          | Output                                                                                  |\n| ------------------------------------------------ | --------------- | --------------------------------------------------------------------------------------- |\n| [Website](./generators/html.html)                | `html`          | The site: server-rendered pages with interactive islands, bundled with Vite by default. |\n| [Section pages](./generators/section-pages.html) | `section-pages` | An extra page for each section of every module, added to the website and the sitemap.   |\n| [Search index](./generators/orama-db.html)       | `orama-db`      | `orama-db.json`, the Orama index that the website's search box loads.                   |\n| [Sitemap](./generators/sitemap.html)             | `sitemap`       | `sitemap.xml`, listing the pages for search engines.                                    |\n\n* The search box shows only when the search index is built in the same run.\n  Set [`showSearchBox`](./generators/html.html#configuring) in the `html` section\n  to choose yourself.\n* `section-pages` adds its pages to whichever of `html` and `sitemap` you also\n  ask for. Ask for it on its own and you get both.","summary":"From `@doc-kit/generator-react`, which you install next to the CLI.","examples":[],"children":[]},{"kind":"section","id":"for-language-models","name":"For language models","title":"For language models","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From [`@doc-kit/generator-react`](./packages/react.html).\n\n| Generator                                        | Target          | Output                                                                  |\n| ------------------------------------------------ | --------------- | ----------------------------------------------------------------------- |\n| [llms.txt](./generators/llms-txt.html)           | `llms-txt`      | An [`llms.txt`](https://llmstxt.org/) index linking to each page.       |\n| [llms-full.txt](./generators/llms-txt-full.html) | `llms-txt-full` | `llms-full.txt`: every page's Markdown in one file, each after its URL. |","summary":"From `@doc-kit/generator-react`.","examples":[],"children":[]},{"kind":"section","id":"data","name":"Data","title":"Data","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From [`@doc-kit/core`](./packages/core.html), which comes with the CLI.\n\n| Generator                                   | Target        | Output                                                                 |\n| ------------------------------------------- | ------------- | ---------------------------------------------------------------------- |\n| [JSON](./generators/json.html)              | `json`        | One JSON document per source file, described by a published schema.    |\n| [JSON bundle](./generators/json-all.html)   | `json-all`    | Every `json` document bundled into one `all.json`.                     |\n| [Debug JSON](./generators/json-simple.html) | `json-simple` | `api-docs.json`, a dump of the API entries for debugging the pipeline. |","summary":"From `@doc-kit/core`, which comes with the CLI.","examples":[],"children":[]},{"kind":"section","id":"for-nodejs","name":"For Node.js","title":"For Node.js","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From [`@node-core/doc-kit`](./packages/node.html), which you install next to the\nCLI. These serve the Node.js project's own build, release and tests, and their\ndefaults match its layout, so they're mostly useful to Node.js and projects\nshaped like it.\n\n| Generator                                        | Target         | Output                                                                               |\n| ------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------ |\n| [Man page](./generators/man-page.html)           | `man-page`     | A man page in mdoc format (`node.1` by default), from a command-line reference page. |\n| [API links](./generators/api-links.html)         | `api-links`    | `apilinks.json`, mapping each exported API to the line defining it in the sources.   |\n| [Addon examples](./generators/addon-verify.html) | `addon-verify` | The C++ addon examples' code blocks, written out with a `binding.gyp` for the tests. |","summary":"From `@node-core/doc-kit`, which you install next to the CLI. These serve the Node.js project's own build, release and tests, and their defaults match its layout, so they're mostly useful to Node.js and projects shaped like it.","examples":[],"children":[]},{"kind":"section","id":"nodejss-legacy-formats","name":"Node.js's legacy formats","title":"Node.js's legacy formats","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From [`@node-core/doc-kit-legacy`](./packages/node-legacy.html), which you\ninstall next to the CLI. These write the HTML pages and JSON files of the\nNode.js API docs in the formats Node.js's original tooling made, for Node.js\nand the tools that read them. For your own docs, use the website and JSON\ngenerators above.\n\n| Generator                                                    | Target            | Output                                                                   |\n| ------------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------ |\n| [Legacy HTML](./generators/legacy-html.html)                 | `legacy-html`     | A classic Node.js HTML page per source file, with its `assets/`.         |\n| [Legacy single-page HTML](./generators/legacy-html-all.html) | `legacy-html-all` | `all.html`, every legacy HTML page one after another.                    |\n| [Legacy JSON](./generators/legacy-json.html)                 | `legacy-json`     | A classic Node.js JSON file per source file, with descriptions in HTML.  |\n| [Legacy JSON bundle](./generators/legacy-json-all.html)      | `legacy-json-all` | `all.json`, the sections of every legacy JSON file merged into one file. |","summary":"From `@node-core/doc-kit-legacy`, which you install next to the CLI. These write the HTML pages and JSON files of the Node.js API docs in the formats Node.js's original tooling made, for Node.js and the tools that read them. For your own docs, use the website and JSON generators above.","examples":[],"children":[]},{"kind":"section","id":"pipeline-stages","name":"Pipeline stages","title":"Pipeline stages","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The generators above read from a few shared stages, which are generators too. A\nstage runs when a target needs it, once per run however many targets read it,\nand writes no files. You don't ask for stages yourself, but you configure them\nlike any other generator: `--type-map`, for example, sets `metadata.typeMap`.\n\n| Stage                                          | Name       | Produces                                                                            |\n| ---------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |\n| [Parsing Markdown](./generators/ast.html)      | `ast`      | The Markdown and MDX files in `input`, parsed into syntax trees in worker threads.  |\n| [Parsing JavaScript](./generators/ast-js.html) | `ast-js`   | The `.js` files in `input`, parsed with Acorn for `api-links`.                      |\n| [API entries](./generators/metadata.html)      | `metadata` | The flat list of API entries, one per heading with its kind, stability and history. |\n| [Page JSX](./generators/jsx-ast.html)          | `jsx-ast`  | Each page as a JSX program, which `html` renders.                                   |\n\n`jsx-ast` comes from `@doc-kit/generator-react`; the other stages come from\n`@doc-kit/core`.","summary":"The generators above read from a few shared stages, which are generators too. A stage runs when a target needs it, once per run however many targets read it, and writes no files. You don't ask for stages yourself, but you configure them like any other generator: `--type-map`, for example, sets `metadata.typeMap`.","examples":[],"children":[]},{"kind":"section","id":"options","name":"Options","title":"Options","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each generator reads its options from the configuration section named after\nit. See [Generator options](./configuration.html#generator-options).","summary":"Each generator reads its options from the configuration section named after it. See Generator options.","examples":[],"children":[]},{"kind":"section","id":"your-own","name":"Your own","title":"Your own","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A target can also be an import specifier: a package export, or the path to a\nlocal file (starting with `.`, or absolute) whose default export is a generator.\nIt runs alongside the built-in ones, and reads its options from the section\nnamed after its `name`.\n\n```bash\nnpx @doc-kit/cli generate -t @my-scope/my-generator -t ./generators/rss.mjs ...\n```\n\nTo write one, see [Creating generators](./creating-generators.html).","summary":"A target can also be an import specifier: a package export, or the path to a local file (starting with `.`, or absolute) whose default export is a generator. It runs alongside the built-in ones, and reads its options from the section named after its `name`.","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli generate -t @my-scope/my-generator -t ./generators/rss.mjs ..."}],"children":[]}]}