{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"packages-cli","path":"/packages/cli","type":"module","module":"packages-cli","title":"`@doc-kit/cli`","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The command-line interface of [doc-kit](https://doc-kit.nodejs.org), the\nNode.js project's toolkit for API documentation. Its `doc-kit` command reads\nyour docs and runs generators that write a website, the search index, JSON,\n`llms.txt`, man pages, or whatever a custom generator produces. Use it to\nbuild your docs locally and in CI.","summary":"The command-line interface of doc-kit, the Node.js project's toolkit for API documentation. Its `doc-kit` command reads your docs and runs generators that write a website, the search index, JSON, `llms.txt`, man pages, or whatever a custom generator produces. Use it to build your docs locally and in CI.","examples":[],"children":[{"kind":"section","id":"install","name":"Install","title":"Install","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\n```\n\nThe CLI comes with [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core)\nand its JSON generators. The other generators live in their own packages,\nwhich you install next to the CLI. The command above adds the website\ngenerators; leave `@doc-kit/generator-react` out if you only need JSON.\n\n| Package                                                                 | Generators                                                                  |\n| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |\n| [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core)             | `json`, `json-all`, `json-simple`                                           |\n| [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) | `html`, `section-pages`, `orama-db`, `sitemap`, `llms-txt`, `llms-txt-full` |\n| [`@node-core/doc-kit`](https://doc-kit.nodejs.org/packages/node)        | `man-page`, `api-links`, `addon-verify`                                     |","summary":"The CLI comes with `@doc-kit/core` and its JSON generators. The other generators live in their own packages, which you install next to the CLI. The command above adds the website generators; leave `@doc-kit/generator-react` out if you only need JSON.","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @doc-kit/generator-react"}],"children":[]},{"kind":"section","id":"build-your-docs","name":"Build your docs","title":"Build your docs","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx doc-kit generate -t html -t orama-db -i \"docs/**/*.md\" -o out\n```\n\nThis builds the website and its search index from every Markdown file under\n`docs/`, and writes them to `out/`. A run needs at least a target and an\ninput, from flags or a [configuration file](#configuration):\n\n* `-t, --target <generator...>` {string[]} The generators to run. Repeat the\n  flag, or list several names after it.\n* `-i, --input <patterns...>` {string[]} Glob patterns matching your source\n  files. Quote them, so your shell passes them on unexpanded.\n* `-o, --output <directory>` {string} The directory the generators write to.\n\nRun `npx doc-kit generate --help`, or see the\n[CLI reference](https://doc-kit.nodejs.org/cli), for every option.","summary":"This builds the website and its search index from every Markdown file under `docs/`, and writes them to `out/`. A run needs at least a target and an input, from flags or a configuration file:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t html -t orama-db -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"preview-the-output","name":"Preview the output","title":"Preview the output","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx doc-kit preview\n```\n\nThis serves `./out` on <http://localhost:3000> as it is, without reading your\nconfiguration file. Pass it any `generate` option and it builds first, then\nserves the directory that build wrote to. If your build writes somewhere other\nthan `./out`, pass your configuration file (or `-o`) so it builds and serves\nthat directory:\n\n```bash\nnpx doc-kit preview --config-file doc-kit.config.mjs\n```\n\nIt builds once and doesn't watch for changes, so run it again after editing.\nTwo options of its own control the server:\n\n* `--port <number>` {number} The port to serve on. **Default:** `3000`.\n* `--host <host>` {string} The host to listen on. **Default:** `'localhost'`.\n\n> \\[!NOTE]\n> The preview server is meant for checking your docs locally. To put them\n> online, upload the output directory to a static host; see\n> [Publishing your docs](https://doc-kit.nodejs.org/publishing).","summary":"This serves `./out` on http://localhost:3000 as it is, without reading your configuration file. Pass it any `generate` option and it builds first, then serves the directory that build wrote to. If your build writes somewhere other than `./out`, pass your configuration file (or `-o`) so it builds and serves that directory:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit preview"},{"language":"bash","displayName":null,"code":"npx doc-kit preview --config-file doc-kit.config.mjs"}],"children":[]},{"kind":"section","id":"configuration","name":"Configuration","title":"Configuration","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Instead of passing flags on every run, put your options in a configuration\nfile:\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n};\n```\n\nWith this file in place, `npx doc-kit generate` needs no flags. doc-kit looks\nfor it in the working directory, as `doc-kit.config.mjs` (or `.js`, `.cjs`),\na `.doc-kitrc` file in JSON, YAML or JavaScript, or a `doc-kit` key in\n`package.json`. Pass `--config-file <path>` to load another file. A flag wins\nover the file when both set the same option.\n\nThe [configuration reference](https://doc-kit.nodejs.org/configuration)\ncovers every option, including each generator's own.","summary":"Instead of passing flags on every run, put your options in a configuration file:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n};"}],"children":[]},{"kind":"section","id":"custom-generators","name":"Custom generators","title":"Custom generators","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`--target`, and `target` in the configuration file, also take a generator you\nwrote or installed: a relative path such as `./my-generator.mjs` (resolved\nfrom the working directory), an absolute path, or a package name. The\nmodule's default export must have a `name` and a `generate` function.\n\n```bash\nnpx doc-kit generate -t ./my-generator.mjs -i \"docs/**/*.md\" -o out\n```\n\n[Creating generators](https://doc-kit.nodejs.org/creating-generators) shows\nhow to write one.","summary":"`--target`, and `target` in the configuration file, also take a generator you wrote or installed: a relative path such as `./my-generator.mjs` (resolved from the working directory), an absolute path, or a package name. The module's default export must have a `name` and a `generate` function.","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t ./my-generator.mjs -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"log-level","name":"Log level","title":"Log level","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`--log-level <level>` works with every command. It takes `debug`, `info`,\n`warn`, `error` or `fatal`, and defaults to `info`:\n\n```bash\nnpx doc-kit --log-level debug generate\n```","summary":"`--log-level <level>` works with every command. It takes `debug`, `info`, `warn`, `error` or `fatal`, and defaults to `info`:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit --log-level debug generate"}],"children":[]},{"kind":"section","id":"documentation","name":"Documentation","title":"Documentation","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* [Getting started](https://doc-kit.nodejs.org/getting-started): from an empty\n  folder to a site with search.\n* [CLI](https://doc-kit.nodejs.org/cli): every command and option.\n* [Configuration](https://doc-kit.nodejs.org/configuration): the\n  configuration file and how it merges with flags.\n* [Generators](https://doc-kit.nodejs.org/generators): what each generator\n  writes.","summary":"","examples":[],"children":[]},{"kind":"section","id":"contributing","name":"Contributing","title":"Contributing","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"This package lives in `packages/cli` of the\n[nodejs/doc-kit](https://github.com/nodejs/doc-kit) monorepo, which uses\nNode.js 24 and pnpm:\n\n```bash\ngit clone https://github.com/nodejs/doc-kit.git\ncd doc-kit\npnpm install\n\n# Run the CLI from source\nnode --run run -- generate --help\n\n# Run it again whenever a file it imports changes\nnode --run watch -- generate -t json -i \"path/to/docs/**/*.md\" -o out\n```\n\nEach command is a module in `bin/commands/`;\n[Adding a command](https://doc-kit.nodejs.org/contributing/commands) walks\nthrough writing one. Run the tests with `node --run test`, and add a changeset\nwith `node --run changeset` for any change users will notice. The\n[contributing guide](https://github.com/nodejs/doc-kit/blob/main/CONTRIBUTING.md)\nhas the rest.","summary":"This package lives in `packages/cli` of the nodejs/doc-kit monorepo, which uses Node.js 24 and pnpm:","examples":[{"language":"bash","displayName":null,"code":"git clone https://github.com/nodejs/doc-kit.git\ncd doc-kit\npnpm install\n\n# Run the CLI from source\nnode --run run -- generate --help\n\n# Run it again whenever a file it imports changes\nnode --run watch -- generate -t json -i \"path/to/docs/**/*.md\" -o out"}],"children":[]}]}