CLI

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:

npx doc-kit <command> [options]

npx doc-kit --help lists the commands, and npx doc-kit generate --help the options of one.

Runs the generators and writes their output. It needs at least one target and an input, from flags or a configuration file:

npx doc-kit generate -t html -t orama-db -i "docs/**/*.md" -o out

Quote glob patterns, so they reach doc-kit as written instead of being expanded by your shell. Options that take a list accept several values after one flag (-t html orama-db) or the flag repeated (-t html -t orama-db). Each option except --config-file sets the configuration key named in parentheses.

• -t, --target string[] Generators to run (target): built-in names, such as html or orama-db (see the generators overview), or the import specifier or path of a custom generator. Only json, json-all, and json-simple come with the CLI. The others come from packages you install next to it, such as @doc-kit/generator-react for html, orama-db, and the other web generators, and @node-core/doc-kit for man-page, api-links, and addon-verify.
• -i, --input string[] Glob patterns of the files to read (global.input).
• --ignore string[] Glob patterns of files to leave out (global.ignore).
• -o, --output string Directory to write the output to (global.output).
• --config-file string Path of the configuration file to load, instead of searching the working directory for one.
• -v, --version string Version of the project being documented (global.version), coerced to semver, so 22 means 22.0.0. Default: the version of Node.js running doc-kit.
• -c, --changelog string URL or path of a changelog in the format of Node.js's CHANGELOG.md, which the version selector is built from (global.changelog). Without one, the output covers a single version.
• --index string URL or path of an index.md whose list of links (* [Title](file.md)) sets the order of the documents in the JSON bundle (global.index).
• --git-ref string Git branch, tag, or commit that links into your repository point to, such as edit links and the JSON output's source URLs (global.ref). The website's source code links follow jsx-ast.ref instead, which defaults to 'main' and is set in a configuration file. Default: 'HEAD'.
• --type-map string URL or path of a JSON file mapping type names to the URLs documenting them, used to link types (metadata.typeMap).
• --minify boolean Minify the output (global.minify). Default: false.
• -p, --threads number Worker threads to use, at least 1 (threads). Default: the number of CPUs, up to 4.
• --chunk-size number Items each worker processes per task, at least 1 (chunkSize). Default: 10.

# Build everything the configuration file describes
npx doc-kit generate

# Build only the JSON output, minified, into dist/json
npx doc-kit generate -t json -o dist/json --minify

When something fails, doc-kit logs the error and exits with code 1, so a broken build also fails your CI job.

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:

npx doc-kit preview

What it serves depends on the options you pass:

• No generate options: it serves ./out as it is, without reading your configuration file, and stops with an error if ./out doesn't exist.
• Any generate option: it builds first, exactly as doc-kit generate would, then serves the directory that build wrote to. To build from your configuration file alone, pass it with --config-file.

It builds once and doesn't watch for changes, so run it again after editing. Directories serve their index.html, and paths that don't exist get the output's 404.html, when it has one.

It takes these options, plus every option of doc-kit generate:

# Build with the configuration file, then serve its output directory
npx doc-kit preview --config-file doc-kit.config.mjs

# Build only the site, then serve it on another port
npx doc-kit preview -t html --port 8080

These work with every command, before or after its name:

npx doc-kit generate --log-level debug

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.

Flags win over the file. A flag that takes a list, such as --target, replaces the configured list instead of adding to it. See Configuration for the file's format and every key.