Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
33c10e7
docs: rewrite and restructure the documentation
ovflowd Oct 27, 2026
3261124
feat(www): redesign doc-kit.nodejs.org
ovflowd Oct 27, 2026
a404412
fix(react): replay the press that hydrates an island
ovflowd Oct 27, 2026
7a853ec
refactor(www): skip comments instead of stripping them when inlining …
ovflowd Oct 27, 2026
0bdd6bb
refactor(react): keep the press events with the other UI constants
ovflowd Oct 27, 2026
6835ddf
chore(www): make the site its own workspace package
ovflowd Oct 27, 2026
4c571b6
chore(www): add the source of the social preview image
ovflowd Oct 27, 2026
b76d1bc
feat(www): make the benchmarks reproducible
ovflowd Oct 27, 2026
b7992df
docs: give every generator its own page again
ovflowd Oct 27, 2026
42d666a
feat(www): write the home page in MDX on doc-kit's own code blocks
ovflowd Oct 27, 2026
32fef69
docs: link to one place instead of repeating it
ovflowd Oct 29, 2026
16c9eda
fix(react): scope the heading layout and mark the selected code tab
ovflowd Oct 29, 2026
965c875
refactor(www): drop the workarounds doc-kit no longer needs
ovflowd Oct 29, 2026
cc27b62
feat(www): build the all page and take more from the configuration
ovflowd Oct 29, 2026
81e70af
docs(react): shorten the comment on held presses
ovflowd Oct 29, 2026
a2ff6b2
refactor: move the benchmark to scripts/ and slim it down
ovflowd Oct 29, 2026
22bce64
docs: make the diagrams self-contained and play them once
ovflowd Oct 29, 2026
ea0b9f9
feat(www): draw the home page's animations as SVGs
ovflowd Oct 29, 2026
22c3b2c
refactor(www): keep the home page's main landmark on a div
ovflowd Oct 29, 2026
b968eab
feat(www): polish Kit's head
ovflowd Oct 29, 2026
607ac4e
chore(www): format the social card's source
ovflowd Oct 29, 2026
70fc4db
fix(www): bring back the site and search previews
ovflowd Oct 29, 2026
0bf2a4e
docs: format the guides with oxfmt 0.74
ovflowd Nov 6, 2026
a713a85
fix(react): replay the press that starts an island loading
ovflowd Nov 6, 2026
caa2360
docs: measure the benchmarks again now that #1179 has landed
ovflowd Nov 6, 2026
66d05c4
test: add versioned pageURL tests for canonical function
bmuenzenmeyer Nov 7, 2026
e487647
fix(react): link the release line and the index's directory as canonical
ovflowd Nov 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
docs: rewrite and restructure the documentation
Rewrites every page, package README and generator README for clarity and
accuracy against the code, and splits the docs into guides, which teach a
task with one running example, and reference pages, which list every
option. Guides link to the reference instead of repeating it.

- `index.md` becomes `introduction.md`, and a new guide covers documenting
  TypeScript and JSDoc with `@doc-kit/typedoc`.
- Every generator page follows one layout: what it makes, what it reads
  and writes, usage, options, then details.
- The specification gains a reading guide, a table of its constructs and
  examples for every directive, and resolves rules it stated as both MUST
  and SHOULD.
- Code examples whose Markdown bullets the formatter rewrote (the
  changelog, `index.md` and `llms.txt` samples) are plain text again, so
  they show what doc-kit actually reads and writes.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
  • Loading branch information
ovflowd committed Nov 17, 2026
commit 33c10e7535c66d299bb51f0a5c75d01981ddf146
166 changes: 125 additions & 41 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -1,61 +1,145 @@
# CLI

The `doc-kit` command-line interface. Every option that maps to
configuration can also live in a [configuration file](./configuration.md);
when both are present, CLI flags win (rule of specifity).
The `doc-kit` command builds your docs with `doc-kit generate` and serves
Comment thread
ovflowd marked this conversation as resolved.
Resolved
them locally with `doc-kit preview`. It comes from the
[`@doc-kit/cli`](./packages/cli.md) package; install it in your project as
shown in [Getting started](./getting-started.md), then run it with `npx`:

```bash
npx @doc-kit/cli [command] [options]
npx doc-kit <command> [options]
```

One option applies to every command:

- `--log-level <level>` {string} `debug`, `info`, `warn`, `error`, or
`fatal`. **Default:** `'info'`.
`npx doc-kit --help` lists the commands, and `npx doc-kit 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](#configuration-files):

```bash
npx @doc-kit/cli generate [options]
npx doc-kit generate -t html -t orama-db -i "docs/**/*.md" -o out
```

Runs the generators and writes their output. Requires a `target` and an
`input`, from flags or the configuration file.

- `--config-file <path>` {string} Use a specific configuration file instead
of searching.
- `-i, --input <patterns...>` {string[]} Input file patterns (glob).
- `-t, --target <name...>` {string[]} Generator name(s), or import
specifiers for custom generators.
- `--ignore <patterns...>` {string[]} Input patterns to skip.
- `-o, --output <dir>` {string} The output directory.
- `-v, --version <semver>` {string} The version of the project being
documented.
- `-c, --changelog <url>` {string} Changelog URL or path (release history
for version selectors).
- `--git-ref <ref>` {string} Git ref used in source links.
- `--index <url>` {string} `index.md` URL or path.
- `--minify` {boolean} Minify the output.
- `--type-map <url>` {string} Type map URL or path (custom type-name → URL
links).
- `-p, --threads <n>` {number} Worker threads to use (minimum 1).
- `--chunk-size <n>` {number} Items per worker thread (minimum 1).
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](./generators.md)),
or the import specifier or path of a
[custom generator](./creating-generators.md). Only `json`, `json-all`, and
Comment thread
ovflowd marked this conversation as resolved.
Resolved
`json-simple` come with the CLI. The others come from packages you install
next to it, such as [`@doc-kit/generator-react`](./packages/react.md) for
`html`, `orama-db`, and the other web generators, and
[`@node-core/doc-kit`](./packages/node.md) 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`](./generators/jsx-ast.md#configuring) 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`).
Comment thread
ovflowd marked this conversation as resolved.
Resolved
**Default:** the number of CPUs, up to 4.
- `--chunk-size` {number} Items each worker processes per task, at least 1
(`chunkSize`). **Default:** `10`.

```bash
# 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.

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

```bash
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`](#doc-kit-generate):

- `--port` {number} Port to serve on; `0` picks a free one. **Default:**
`3000`.
- `--host` {string} Host to listen on; `0.0.0.0` makes the preview reachable
from other devices on your network. **Default:** `'localhost'`.

```bash
# 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
```

> [!NOTE]
> The preview server is for local testing, not for production. To publish,
> upload the output directory to a static host; see
> [Publishing your docs](./publishing.md).

## Global options

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

- `--log-level` {string} Log only messages at this level or above: `debug`,
`info`, `warn`, `error`, or `fatal`. **Default:** `'info'`.

```bash
npx @doc-kit/cli preview [options]
npx doc-kit generate --log-level debug
```

Serves the generated docs over HTTP for local verification. Every `generate`
option is accepted: when any of them is passed, the docs are built first
(same semantics as `doc-kit generate`); otherwise the existing output
directory is served as-is (`./out` by default).
## Configuration files

> **Note:** The preview server is meant for local testing only — it is not
> production grade. Do not use it to deploy your documentation.
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](./configuration.md#where-configuration-lives) for
every name it tries.

- `--port <n>` {number} Port to serve on. **Default:** `3000`.
- `--host <host>` {string} Host to listen on (e.g. `localhost`, `0.0.0.0`).
**Default:** `'localhost'`.
- Every option of [`doc-kit generate`](#doc-kit-generate).
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](./configuration.md) for the file's format and every key.
Loading