{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"cli","path":"/cli","type":"module","module":"cli","title":"CLI","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `doc-kit` command builds your docs with `doc-kit generate` and serves\nthem locally with `doc-kit preview`. It comes from the\n[`@doc-kit/cli`](./packages/cli.html) package; install it in your project as\nshown in [Getting started](./getting-started.html), then run it with `npx`:\n\n```bash\nnpx doc-kit <command> [options]\n```\n\n`npx doc-kit --help` lists the commands, and `npx doc-kit generate --help`\nthe options of one.","summary":"The `doc-kit` command builds your docs with `doc-kit generate` and serves them locally with `doc-kit preview`. It comes from the `@doc-kit/cli` package; install it in your project as shown in Getting started, then run it with `npx`:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit <command> [options]"}],"children":[{"kind":"section","id":"doc-kit-generate","name":"doc-kit generate","title":"`doc-kit generate`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Runs the generators and writes their output. It needs at least one target\nand an input, from flags or a [configuration file](#configuration-files):\n\n```bash\nnpx doc-kit generate -t html -t orama-db -i \"docs/**/*.md\" -o out\n```\n\nQuote glob patterns, so they reach doc-kit as written instead of being\nexpanded by your shell. Options that take a list accept several values after\none flag (`-t html orama-db`) or the flag repeated (`-t html -t orama-db`).\nEach option except `--config-file` sets the configuration key named in\nparentheses.\n\n* `-t`, `--target` {string[]} Generators to run (`target`): built-in names,\n  such as `html` or `orama-db` (see the [generators overview](./generators.html)),\n  or the import specifier or path of a\n  [custom generator](./creating-generators.html). Only `json`, `json-all`, and\n  `json-simple` come with the CLI. The others come from packages you install\n  next to it, such as [`@doc-kit/generator-react`](./packages/react.html) for\n  `html`, `orama-db`, and the other web generators, and\n  [`@node-core/doc-kit`](./packages/node.html) for `man-page`, `api-links`, and\n  `addon-verify`.\n* `-i`, `--input` {string[]} Glob patterns of the files to read\n  (`global.input`).\n* `--ignore` {string[]} Glob patterns of files to leave out (`global.ignore`).\n* `-o`, `--output` {string} Directory to write the output to\n  (`global.output`).\n* `--config-file` {string} Path of the configuration file to load, instead\n  of searching the working directory for one.\n* `-v`, `--version` {string} Version of the project being documented\n  (`global.version`), coerced to semver, so `22` means `22.0.0`.\n  **Default:** the version of Node.js running doc-kit.\n* `-c`, `--changelog` {string} URL or path of a changelog in the format of\n  Node.js's `CHANGELOG.md`, which the version selector is built from\n  (`global.changelog`). Without one, the output covers a single version.\n* `--index` {string} URL or path of an `index.md` whose list of links\n  (`* [Title](file.md)`) sets the order of the documents in the JSON bundle\n  (`global.index`).\n* `--git-ref` {string} Git branch, tag, or commit that links into your\n  repository point to, such as edit links and the JSON output's source URLs\n  (`global.ref`). The website's source code links follow\n  [`jsx-ast.ref`](./generators/jsx-ast.html#configuring) instead, which defaults\n  to `'main'` and is set in a configuration file. **Default:** `'HEAD'`.\n* `--type-map` {string} URL or path of a JSON file mapping type names to the\n  URLs documenting them, used to link types (`metadata.typeMap`).\n* `--minify` {boolean} Minify the output (`global.minify`). **Default:**\n  `false`.\n* `-p`, `--threads` {number} Worker threads to use, at least 1 (`threads`).\n  **Default:** the number of CPUs, up to 4.\n* `--chunk-size` {number} Items each worker processes per task, at least 1\n  (`chunkSize`). **Default:** `10`.\n\n```bash\n# Build everything the configuration file describes\nnpx doc-kit generate\n\n# Build only the JSON output, minified, into dist/json\nnpx doc-kit generate -t json -o dist/json --minify\n```\n\nWhen something fails, doc-kit logs the error and exits with code 1, so a\nbroken build also fails your CI job.","summary":"Runs the generators and writes their output. It needs at least one 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"},{"language":"bash","displayName":null,"code":"# Build everything the configuration file describes\nnpx doc-kit generate\n\n# Build only the JSON output, minified, into dist/json\nnpx doc-kit generate -t json -o dist/json --minify"}],"children":[]},{"kind":"section","id":"doc-kit-preview","name":"doc-kit preview","title":"`doc-kit preview`","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Serves the output directory over HTTP at <http://localhost:3000>, so you can\ncheck a build in the browser the way a host would serve it:\n\n```bash\nnpx doc-kit preview\n```\n\nWhat it serves depends on the options you pass:\n\n* **No `generate` options:** it serves `./out` as it is, without reading your\n  configuration file, and stops with an error if `./out` doesn't exist.\n* **Any `generate` option:** it builds first, exactly as `doc-kit generate`\n  would, then serves the directory that build wrote to. To build from your\n  configuration file alone, pass it with `--config-file`.\n\nIt builds once and doesn't watch for changes, so run it again after editing.\nDirectories serve their `index.html`, and paths that don't exist get the\noutput's `404.html`, when it has one.\n\nIt takes these options, plus every option of\n[`doc-kit generate`](#doc-kit-generate):\n\n* `--port` {number} Port to serve on; `0` picks a free one. **Default:**\n  `3000`.\n* `--host` {string} Host to listen on; `0.0.0.0` makes the preview reachable\n  from other devices on your network. **Default:** `'localhost'`.\n\n```bash\n# Build with the configuration file, then serve its output directory\nnpx doc-kit preview --config-file doc-kit.config.mjs\n\n# Build only the site, then serve it on another port\nnpx doc-kit preview -t html --port 8080\n```\n\n> \\[!NOTE]\n> The preview server is for local testing, not for production. To publish,\n> upload the output directory to a static host; see\n> [Publishing your docs](./publishing.html).","summary":"Serves the output directory over HTTP at http://localhost:3000, so you can check a build in the browser the way a host would serve it:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit preview"},{"language":"bash","displayName":null,"code":"# Build with the configuration file, then serve its output directory\nnpx doc-kit preview --config-file doc-kit.config.mjs\n\n# Build only the site, then serve it on another port\nnpx doc-kit preview -t html --port 8080"}],"children":[]},{"kind":"section","id":"global-options","name":"Global options","title":"Global options","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"These work with every command, before or after its name:\n\n* `--log-level` {string} Log only messages at this level or above: `debug`,\n  `info`, `warn`, `error`, or `fatal`. **Default:** `'info'`.\n\n```bash\nnpx doc-kit generate --log-level debug\n```","summary":"These work with every command, before or after its name:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate --log-level debug"}],"children":[]},{"kind":"section","id":"configuration-files","name":"Configuration files","title":"Configuration files","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Everything the `generate` flags set can also live in a configuration file,\nalong with what they don't cover, such as generator options, Markdown plugins,\nand presets. Without `--config-file`, doc-kit looks for one in the working\ndirectory, such as `doc-kit.config.mjs`, `.doc-kitrc.yml`, or a `doc-kit` key\nin `package.json`. See\n[Where configuration lives](./configuration.html#where-configuration-lives) for\nevery name it tries.\n\nFlags win over the file. A flag that takes a list, such as `--target`,\nreplaces the configured list instead of adding to it. See\n[Configuration](./configuration.html) for the file's format and every key.","summary":"Everything the `generate` flags set can also live in a configuration file, along with what they don't cover, such as generator options, Markdown plugins, and presets. Without `--config-file`, doc-kit looks for one in the working directory, such as `doc-kit.config.mjs`, `.doc-kitrc.yml`, or a `doc-kit` key in `package.json`. See Where configuration lives for every name it tries.","examples":[],"children":[]}]}