Skip to content

Latest commit

 

History

History
135 lines (107 loc) · 5.49 KB

cli.md

File metadata and controls

135 lines (107 loc) · 5.49 KB

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/cli [command] [options]

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

doc-kit generate

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 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 <name...> {string[]} Generators to run (target): built-in names, such as html or orama-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, so 22 means 22.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's CHANGELOG.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 an index.md whose 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 follow jsx-ast.ref instead, 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 --minify

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

doc-kit preview

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 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:

  • --port <n> {number} Port to serve on; 0 picks 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 8080

Warning

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.

Global options

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, or fatal. Default: 'info'.
npx @doc-kit/cli generate --log-level debug

Configuration files

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.