feat: redesign doc-kit.nodejs.org

.changeset/gentle-kittens-replay.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+Replay the click or tap that hydrates a code block, so its first press switches tabs or copies the code

.oxfmtrc.json

@@ -29,6 +29,7 @@
     "packages/node/src/api-links/__tests__/fixtures/",
     "*.snapshot",
     "packages/react/src/html/template.html",
+    "www/theme/template.html",
     "out/",
     "www/content/",
     "www/out/",

.oxlintrc.json

@@ -207,6 +207,7 @@
       "files": [
         "packages/node-legacy/src/legacy-html/assets/*.js",
         "packages/react/src/html/ui/**/*",
+        "www/theme/components/**/*",
         "e2e/**/*.spec.js"
       ],
       "globals": {

CONTRIBUTING.md

@@ -85,10 +85,12 @@ published package lives under `packages/`:
 - `packages/typedoc`: [`@doc-kit/typedoc`](packages/typedoc) — the TypeDoc plugin writing API references as doc-kit Markdown
 
 Everything else at the root supports the repo rather than shipping to npm:
-`docs/` (every authored documentation page, from the landing page to the
-reference docs), `www/` (the documentation site build: its configuration and
-gitignored build artifacts), `scripts/` (build and comparison helpers), and
-`e2e/` (Playwright tests).
+`docs/` (the authored guides and reference docs, plus the illustrations in
+`docs/diagrams/`), `www/` (the documentation site: its configuration, its theme
+in `www/theme/`, site-only pages such as the home page in `www/pages/`, public
+files in `www/public/`, and the gitignored build artifacts in `www/content/`
+and `www/out/`), `scripts/` (build and comparison helpers), and `e2e/`
+(Playwright tests).
 
 Contributor-facing deep dives — [creating CLI
 commands](docs/contributing/commands.md) and [creating

docs/cli.md

@@ -1,42 +1,146 @@
 # 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 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](./generators.md)),
+  or the import specifier or path of a
+  [custom generator](./creating-generators.md). 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`](./packages/react.md) for
+  `html`, `orama-db`, and the other web generators,
+  [`@node-core/doc-kit`](./packages/node.md) for `man-page`, `api-links`, and
+  `addon-verify`, and [`@node-core/doc-kit-legacy`](./packages/node-legacy.md)
+  for the `legacy-*` generators.
+- `-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,
+  the legacy HTML sidebar and the legacy 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`).
+  **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 generate [options]
+npx doc-kit generate --log-level debug
 ```
 
-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).
+## 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. 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.
+
+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.