{"$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/cli [command] [options]\n```\n\n`npx @doc-kit/cli --help` lists the commands, and\n`npx @doc-kit/cli generate --help` the 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/cli [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/cli 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 <name...>` {string[]} Generators to run (`target`): built-in\n  names, such as `html` or `orama-db`, or the import specifier or path of a\n  [custom generator](./creating-generators.html). The\n  [generators overview](./generators.html) lists the built-in ones and the\n  package each comes from.\n* `-i, --input <patterns...>` {string[]} Glob patterns of the files to read\n  (`global.input`).\n* `--ignore <patterns...>` {string[]} Glob patterns of files to leave out\n  (`global.ignore`).\n* `-o, --output <dir>` {string} Directory to write the output to\n  (`global.output`).\n* `--config-file <path>` {string} Path of the configuration file to load,\n  instead of searching the working directory for one.\n* `-v, --version <semver>` {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 <url>` {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 <url>` {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  the legacy HTML sidebar and the legacy JSON bundle (`global.index`).\n* `--git-ref <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 <url>` {string} URL or path of a JSON file mapping type names to\n  the URLs documenting them, used to link types (`metadata.typeMap`).\n* `--minify` {boolean} Minify the output (`global.minify`). **Default:**\n  `false`.\n* `-p, --threads <n>` {number} Worker threads to use, at least 1 (`threads`).\n  **Default:** the number of CPUs, up to 4.\n* `--chunk-size <n>` {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/cli generate\n\n# Build only the JSON output, minified, into dist/json\nnpx @doc-kit/cli 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/cli 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/cli generate\n\n# Build only the JSON output, minified, into dist/json\nnpx @doc-kit/cli 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/cli preview [options]\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 <n>` {number} Port to serve on; `0` picks a free one. **Default:**\n  `3000`.\n* `--host <host>` {string} Host to listen on. **Default:** `'localhost'`.\n\n```bash\n# Build with the configuration file, then serve its output directory\nnpx @doc-kit/cli preview --config-file doc-kit.config.mjs\n\n# Build only the site, then serve it on another port\nnpx @doc-kit/cli preview -t html --port 8080\n```\n\n> \\[!WARNING]\n> The preview server is meant for local testing only. It is not a secure,\n> production-grade server: don't expose it to other machines, and don't use\n> it to deploy your documentation. To publish, 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/cli preview [options]"},{"language":"bash","displayName":null,"code":"# Build with the configuration file, then serve its output directory\nnpx @doc-kit/cli preview --config-file doc-kit.config.mjs\n\n# Build only the site, then serve it on another port\nnpx @doc-kit/cli 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 <level>` {string} Log only messages at this level or above:\n  `debug`, `info`, `warn`, `error`, or `fatal`. **Default:** `'info'`.\n\n```bash\nnpx @doc-kit/cli 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/cli 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\n[configuration file](./configuration.html), along with what they don't cover,\nsuch as generator options, Markdown plugins, and presets. Flags win over the\nfile; see [Precedence](./configuration.html#precedence).","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. Flags win over the file; see Precedence.","examples":[],"children":[]}]}