{"$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\n```\n\nGenerator packages are installed separately; see\n[Generators](https://doc-kit.nodejs.org/generators) for the package each\ngenerator comes from.","summary":"Generator packages are installed separately; see Generators for the package each generator comes from.","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli"}],"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/cli generate \\\n  -t html \\\n  -i \"path/to/docs/**/*.md\" \\\n  -o out\n```\n\nA run needs at least a target and an input, from flags or a\n[configuration file](#configuration). Run `npx @doc-kit/cli generate --help`,\nor see the [CLI reference](https://doc-kit.nodejs.org/cli), for every option.","summary":"A run needs at least a target and an input, from flags or a configuration file. Run `npx @doc-kit/cli generate --help`, or see the CLI reference, for every option.","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli generate \\\n  -t html \\\n  -i \"path/to/docs/**/*.md\" \\\n  -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":"To verify the output locally, `preview` serves it over HTTP. Passing any\n`generate` option builds first; otherwise the existing output directory\n(`./out` by default) is served as-is, without reading your configuration file.\n\n```bash\nnpx @doc-kit/cli preview --host localhost --port 3000\n```\n\nIf your build writes somewhere other than `./out`, pass your configuration file\n(or `-o`) so it builds and serves that directory:\n\n```bash\nnpx @doc-kit/cli preview --config-file doc-kit.config.mjs\n```\n\nIt builds once and doesn't watch for changes, so run it again after editing.\n\n> \\[!WARNING]\n> The preview server is not meant to be a secure server. Use it for local\n> testing only, and don't expose it to a network. To put your docs online, see\n> [Publishing your docs](https://doc-kit.nodejs.org/publishing).","summary":"To verify the output locally, `preview` serves it over HTTP. Passing any `generate` option builds first; otherwise the existing output directory (`./out` by default) is served as-is, without reading your configuration file.","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli preview --host localhost --port 3000"},{"language":"bash","displayName":null,"code":"npx @doc-kit/cli 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\n[configuration file](https://doc-kit.nodejs.org/configuration). doc-kit looks\nfor one in the working directory, or loads the file you pass with\n`--config-file <path>`. A flag wins over the file when both set the same\noption.","summary":"Instead of passing flags on every run, put your options in a configuration file. doc-kit looks for one in the working directory, or loads the file you pass with `--config-file <path>`. A flag wins over the file when both set the same option.","examples":[],"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/cli 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/cli generate -t ./my-generator.mjs -i \"docs/**/*.md\" -o out"}],"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\npnpm. From the repository root:\n\n```bash\npnpm install\n\n# Run the CLI from source\npnpm run run generate --help\n\n# Re-run it on every change\npnpm 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 `pnpm test`, and add a changeset with\n`pnpm 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 pnpm. From the repository root:","examples":[{"language":"bash","displayName":null,"code":"pnpm install\n\n# Run the CLI from source\npnpm run run generate --help\n\n# Re-run it on every change\npnpm run watch generate -t json -i \"path/to/docs/**/*.md\" -o out"}],"children":[]}]}