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/cli [command] [options]npx @doc-kit/cli --help lists the commands, and
npx @doc-kit/cli 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/cli generate -t html -t orama-db -i "docs/**/*.md" -o outQuote 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 <name...>{string[]} Generators to run (target): built-in names, such ashtmlororama-db, or the import specifier or path of a custom generator. The generators overview lists the built-in ones and the package each comes from.-i, --input <patterns...>{string[]} Glob patterns of the files to read (global.input).--ignore <patterns...>{string[]} Glob patterns of files to leave out (global.ignore).-o, --output <dir>{string} Directory to write the output to (global.output).--config-file <path>{string} Path of the configuration file to load, instead of searching the working directory for one.-v, --version <semver>{string} Version of the project being documented (global.version), coerced to semver, so22means22.0.0. Default: the version of Node.js running doc-kit.-c, --changelog <url>{string} URL or path of a changelog in the format of Node.js'sCHANGELOG.md, which the version selector is built from (global.changelog). Without one, the output covers a single version.--index <url>{string} URL or path of anindex.mdwhose list of links (* [Title](file.md)) sets the order of the documents in the JSON bundle, the legacy HTML sidebar and the legacy JSON bundle (global.index).--git-ref <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 followjsx-ast.refinstead, which defaults to'main'and is set in a configuration file. Default:'HEAD'.--type-map <url>{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 <n>{number} Worker threads to use, at least 1 (threads). Default: the number of CPUs, up to 4.--chunk-size <n>{number} Items each worker processes per task, at least 1 (chunkSize). Default:10.
# Build everything the configuration file describes
npx @doc-kit/cli generate
# Build only the JSON output, minified, into dist/json
npx @doc-kit/cli generate -t json -o dist/json --minifyWhen 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/cli preview [options]What it serves depends on the options you pass:
- No
generateoptions: it serves./outas it is, without reading your configuration file, and stops with an error if./outdoesn't exist. - Any
generateoption: it builds first, exactly asdoc-kit generatewould, 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:
--port <n>{number} Port to serve on;0picks a free one. Default:3000.--host <host>{string} Host to listen on. Default:'localhost'.
# Build with the configuration file, then serve its output directory
npx @doc-kit/cli preview --config-file doc-kit.config.mjs
# Build only the site, then serve it on another port
npx @doc-kit/cli preview -t html --port 8080Warning
The preview server is meant for local testing only. It is not a secure, production-grade server: don't expose it to other machines, and don't use it to deploy your documentation. To publish, see Publishing your docs.
These work with every command, before or after its name:
--log-level <level>{string} Log only messages at this level or above:debug,info,warn,error, orfatal. Default:'info'.
npx @doc-kit/cli generate --log-level debugEverything 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.