Repository navigation
feat: redesign doc-kit.nodejs.org #1192
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+13,132
−2,261
Merged
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 3261124
feat(www): redesign doc-kit.nodejs.org
ovflowd a404412
fix(react): replay the press that hydrates an island
ovflowd 7a853ec
refactor(www): skip comments instead of stripping them when inlining …
ovflowd 0bdd6bb
refactor(react): keep the press events with the other UI constants
ovflowd 6835ddf
chore(www): make the site its own workspace package
ovflowd 4c571b6
chore(www): add the source of the social preview image
ovflowd b76d1bc
feat(www): make the benchmarks reproducible
ovflowd b7992df
docs: give every generator its own page again
ovflowd 42d666a
feat(www): write the home page in MDX on doc-kit's own code blocks
ovflowd 32fef69
docs: link to one place instead of repeating it
ovflowd 16c9eda
fix(react): scope the heading layout and mark the selected code tab
ovflowd 965c875
refactor(www): drop the workarounds doc-kit no longer needs
ovflowd cc27b62
feat(www): build the all page and take more from the configuration
ovflowd 81e70af
docs(react): shorten the comment on held presses
ovflowd a2ff6b2
refactor: move the benchmark to scripts/ and slim it down
ovflowd 22bce64
docs: make the diagrams self-contained and play them once
ovflowd ea0b9f9
feat(www): draw the home page's animations as SVGs
ovflowd 22c3b2c
refactor(www): keep the home page's main landmark on a div
ovflowd b968eab
feat(www): polish Kit's head
ovflowd 607ac4e
chore(www): format the social card's source
ovflowd 70fc4db
fix(www): bring back the site and search previews
ovflowd 0bf2a4e
docs: format the guides with oxfmt 0.74
ovflowd a713a85
fix(react): replay the press that starts an island loading
ovflowd caa2360
docs: measure the benchmarks again now that #1179 has landed
ovflowd 66d05c4
test: add versioned pageURL tests for canonical function
bmuenzenmeyer e487647
fix(react): link the release line and the index's directory as canonical
ovflowd File filter
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
commit 33c10e7535c66d299bb51f0a5c75d01981ddf146
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| 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 | ||
|
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`). | ||
|
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. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.