diff --git a/.c8rc.json b/.c8rc.json
index 4ce81ec8..49031d7d 100644
--- a/.c8rc.json
+++ b/.c8rc.json
@@ -3,8 +3,8 @@
"exclude": [
"eslint.config.mjs",
"**/fixtures",
- "packages/core/src/generators/legacy-html/assets",
- "packages/core/src/generators/web/ui",
+ "packages/legacy/src/legacy-html/assets",
+ "packages/react/src/html/ui",
"**/*.d.ts"
]
}
diff --git a/.changeset/bootstrap-command.md b/.changeset/bootstrap-command.md
new file mode 100644
index 00000000..d8fbfd11
--- /dev/null
+++ b/.changeset/bootstrap-command.md
@@ -0,0 +1,11 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit bootstrap [generators...]`: sets a project up end to end — a
+`doc-kit.config.mjs` whose naming and versioning are imported straight from
+`package.json`, a documentation directory (detected, or created with a
+starter page), a `.gitignore` entry for the output, and the generator
+packages installed. `doc-kit bootstrap` followed by `doc-kit serve` is all a
+new project needs. Prompts for its few decisions on a TTY; `--yes` accepts
+the defaults.
diff --git a/.changeset/configurable-navigation.md b/.changeset/configurable-navigation.md
index cecf529c..869cdc5e 100644
--- a/.changeset/configurable-navigation.md
+++ b/.changeset/configurable-navigation.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Add `web.navigation`, which supplies the sidebar groups (`navigation.sidebar`)
diff --git a/.changeset/curvy-items-smile.md b/.changeset/curvy-items-smile.md
index 69111d7f..7b9492b4 100644
--- a/.changeset/curvy-items-smile.md
+++ b/.changeset/curvy-items-smile.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': minor
+'@nodejs/doc-kit': minor
---
Discover and load configuration files with `cosmiconfig`.
diff --git a/.changeset/did-you-know-that-the-world-is-round.md b/.changeset/did-you-know-that-the-world-is-round.md
index 98ba0892..b890a4ab 100644
--- a/.changeset/did-you-know-that-the-world-is-round.md
+++ b/.changeset/did-you-know-that-the-world-is-round.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Close Orama search when the target link is on the same page
diff --git a/.changeset/display-name-type-unions.md b/.changeset/display-name-type-unions.md
index 8f91f546..f4b2cdb1 100644
--- a/.changeset/display-name-type-unions.md
+++ b/.changeset/display-name-type-unions.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Resolve unions and arrays of display-name types (`{HTTP/2 Headers Object | vm.Module}`, `{HTTP/2 Headers Object[]}`), and stop capturing prose such as `U+007B ({), and U+007D (}).` as a type annotation.
diff --git a/.changeset/doc-kit-scope-move.md b/.changeset/doc-kit-scope-move.md
new file mode 100644
index 00000000..dd10cf1a
--- /dev/null
+++ b/.changeset/doc-kit-scope-move.md
@@ -0,0 +1,8 @@
+---
+'@nodejs/doc-kit': major
+---
+
+The doc-kit engine and CLI, previously published as `@node-core/doc-kit`,
+are now published as `@nodejs/doc-kit`. The `@node-core/doc-kit` name now
+contains only the Node.js-specific generators (`api-links`, `addon-verify`,
+and `man-page`).
diff --git a/.changeset/fix-relative-parent-path.md b/.changeset/fix-relative-parent-path.md
index e3f7ef8e..7745c39b 100644
--- a/.changeset/fix-relative-parent-path.md
+++ b/.changeset/fix-relative-parent-path.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Fix `relative()` URL resolution when the target path is a prefix of the current
diff --git a/.changeset/install-command.md b/.changeset/install-command.md
new file mode 100644
index 00000000..6a3edf71
--- /dev/null
+++ b/.changeset/install-command.md
@@ -0,0 +1,10 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit install [generators...]`: installs the packages providing the
+given built-in generators (e.g. `doc-kit install html` installs
+`@nodejs/doc-kit-generator-react`). Without arguments, it installs whatever
+the `target` in your configuration file needs. The package manager is
+detected from the project lockfile, and packages land in `devDependencies`
+unless the project depends on doc-kit in production.
diff --git a/.changeset/legacy-kitten-package.md b/.changeset/legacy-kitten-package.md
new file mode 100644
index 00000000..b38a21ca
--- /dev/null
+++ b/.changeset/legacy-kitten-package.md
@@ -0,0 +1,11 @@
+---
+'@nodejs/doc-kit-generator-legacy': major
+'@nodejs/doc-kit': major
+---
+
+The legacy-format generators (`legacy-html`, `legacy-html-all`,
+`legacy-json`, and `legacy-json-all`) now live in the new
+`@nodejs/doc-kit-generator-legacy` package and are loaded via import specifiers such
+as `@nodejs/doc-kit-generator-legacy/legacy-html`. The corresponding
+`@nodejs/doc-kit/*` package exports have been removed. The CLI shorthand
+names are unchanged.
diff --git a/.changeset/monorepo-layout.md b/.changeset/monorepo-layout.md
index 4341e42d..603f5bc6 100644
--- a/.changeset/monorepo-layout.md
+++ b/.changeset/monorepo-layout.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Moved the package into a `packages/core` workspace.
diff --git a/.changeset/node-kitten-package.md b/.changeset/node-kitten-package.md
new file mode 100644
index 00000000..1fa974c2
--- /dev/null
+++ b/.changeset/node-kitten-package.md
@@ -0,0 +1,10 @@
+---
+'@node-core/doc-kit': major
+'@nodejs/doc-kit': major
+---
+
+The Node.js-specific generators (`api-links`, `addon-verify`, and
+`man-page`) now live in the `@node-core/doc-kit` package and are loaded
+via import specifiers such as `@node-core/doc-kit/man-page`. The
+corresponding package exports have been removed from the doc-kit engine.
+The CLI shorthand names are unchanged.
diff --git a/.changeset/node-preset.md b/.changeset/node-preset.md
new file mode 100644
index 00000000..664f1319
--- /dev/null
+++ b/.changeset/node-preset.md
@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': minor
+---
+
+Add the `@node-core/doc-kit/config` preset
diff --git a/.changeset/opt-out-banners.md b/.changeset/opt-out-banners.md
index 652dee33..53f9497a 100644
--- a/.changeset/opt-out-banners.md
+++ b/.changeset/opt-out-banners.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': minor
+'@nodejs/doc-kit': minor
---
Add banner opt-out
diff --git a/.changeset/plain-defaults.md b/.changeset/plain-defaults.md
new file mode 100644
index 00000000..56ae327b
--- /dev/null
+++ b/.changeset/plain-defaults.md
@@ -0,0 +1,6 @@
+---
+'@nodejs/doc-kit': patch
+'@nodejs/doc-kit-generator-react': minor
+---
+
+Defaults are now project-neutral instead of Node.js-specific
diff --git a/.changeset/react-kitten-package.md b/.changeset/react-kitten-package.md
new file mode 100644
index 00000000..25b93ea9
--- /dev/null
+++ b/.changeset/react-kitten-package.md
@@ -0,0 +1,12 @@
+---
+'@nodejs/doc-kit-generator-react': minor
+'@nodejs/doc-kit': major
+---
+
+The React/JSX-based generators (`html` — previously `web` —, `jsx-ast`,
+`llms-txt`, `sitemap`, and `orama-db`) now live in the new
+`@nodejs/doc-kit-generator-react` package and are loaded via import specifiers such as
+`@nodejs/doc-kit-generator-react/html`. The corresponding `@nodejs/doc-kit/*`
+package exports have been removed. The `web` generator is renamed to `html`:
+the CLI shorthand `web` keeps working as a deprecated alias, but the
+configuration key is now `html` instead of `web`.
diff --git a/.changeset/riscv64-warning-spacing.md b/.changeset/riscv64-warning-spacing.md
index 58eff4c4..4b60d25e 100644
--- a/.changeset/riscv64-warning-spacing.md
+++ b/.changeset/riscv64-warning-spacing.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Fix missing spaces in the riscv64 multithreading warning message, which
diff --git a/.changeset/serve-command.md b/.changeset/serve-command.md
new file mode 100644
index 00000000..be9bcbfe
--- /dev/null
+++ b/.changeset/serve-command.md
@@ -0,0 +1,8 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit serve`: generates the documentation, serves the output locally
+(port 3000 by default, falling back to the next available port or honoring
+`--port`), and regenerates whenever the input files change. `--static` serves
+an existing output directory as-is, without generating or watching.
diff --git a/.changeset/short-deprecation-links.md b/.changeset/short-deprecation-links.md
index 8af343c4..7b38dc5c 100644
--- a/.changeset/short-deprecation-links.md
+++ b/.changeset/short-deprecation-links.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Use short `DEP` codes for deprecation heading anchors.
diff --git a/.changeset/spaced-union-types.md b/.changeset/spaced-union-types.md
index 6c831a97..1498134d 100644
--- a/.changeset/spaced-union-types.md
+++ b/.changeset/spaced-union-types.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Space union separators in type annotation values (`{string|URL}` is now rendered as `string | URL`).
diff --git a/.changeset/specifier-generator-loading.md b/.changeset/specifier-generator-loading.md
index 039de74a..e6ee7d58 100644
--- a/.changeset/specifier-generator-loading.md
+++ b/.changeset/specifier-generator-loading.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': minor
+'@nodejs/doc-kit': minor
---
Generators are now loaded dynamically by import specifier instead of a static
diff --git a/.changeset/swc.md b/.changeset/swc.md
index 9b9a2bf2..ec6c6c6e 100644
--- a/.changeset/swc.md
+++ b/.changeset/swc.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Switches `oxc-parser` for `@swc/wasm`, since `oxc-parser` does not provide the needed bindings.
diff --git a/.changeset/tidy-deprecations-smile.md b/.changeset/tidy-deprecations-smile.md
index d9e7c7bb..fa83f542 100644
--- a/.changeset/tidy-deprecations-smile.md
+++ b/.changeset/tidy-deprecations-smile.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Preserve deprecation codes in generated table-of-contents labels.
diff --git a/.changeset/tidy-donuts-search.md b/.changeset/tidy-donuts-search.md
index 9c48fd61..30e045d4 100644
--- a/.changeset/tidy-donuts-search.md
+++ b/.changeset/tidy-donuts-search.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Sync the URL hash when following same-page search hits
diff --git a/.changeset/vite-web-generator.md b/.changeset/vite-web-generator.md
index 49a47ea6..74f4838b 100644
--- a/.changeset/vite-web-generator.md
+++ b/.changeset/vite-web-generator.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': minor
+'@nodejs/doc-kit': minor
---
Make the `web` generator bundler-neutral through a custom adapter contract,
diff --git a/.changeset/yes-i-did-know-that-thank-you.md b/.changeset/yes-i-did-know-that-thank-you.md
index b03124c5..370e2bef 100644
--- a/.changeset/yes-i-did-know-that-thank-you.md
+++ b/.changeset/yes-i-did-know-that-thank-you.md
@@ -1,5 +1,5 @@
---
-'@node-core/doc-kit': patch
+'@nodejs/doc-kit': patch
---
Render markdown `code` snippets in the sidebar
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4702774f..4f68c425 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -141,7 +141,7 @@ jobs:
path: node
- name: Build docs
- run: npx doc-kit generate -t web -i "./node/doc/api/assert.md" -o out
+ run: npx doc-kit generate -t web -i "./node/doc/api/assert.md" -o out --config-file ./e2e/doc-kit.config.mjs
- name: Install Playwright browsers
run: npx playwright install --with-deps
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 02b92068..74e7ee8a 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -56,9 +56,9 @@ jobs:
env:
SLACK_COLOR: '#43853D'
SLACK_ICON: https://github.com/nodejs.png?size=48
- SLACK_TITLE: ':rocket: Package Published: @node-core/doc-kit'
+ SLACK_TITLE: ':rocket: doc-kit Packages Published'
SLACK_MESSAGE: |
- :package: *Package*: `@node-core/doc-kit` ()
+ :package: *Packages*: `nodejs/doc-kit` workspace ()
:bust_in_silhouette: *Published by*: ${{ github.triggering_actor }}
:octocat: *Commit*:
SLACK_USERNAME: nodejs-bot
diff --git a/.gitignore b/.gitignore
index ef3c932b..35a39e94 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,7 +18,7 @@ junit.xml
isolate-*
# Node's Source Folder
-node
+/node
# Playwright
playwright-report/
diff --git a/.prettierignore b/.prettierignore
index 86080826..34ea39e2 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,11 +1,11 @@
npm-shrinkwrap.json
# Tests files
-packages/core/src/generators/api-links/__tests__/fixtures/
+packages/node/src/api-links/__tests__/fixtures/
*.snapshot
# Templates
-packages/core/src/generators/web/template.html
+packages/react/src/html/template.html
# Output
out/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3b806375..faaf19da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
-# `@node-core/doc-kit` Contributing Guide
+# `@nodejs/doc-kit` Contributing Guide
-Thank you for your interest in contributing to the `@node-core/doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better.
+Thank you for your interest in contributing to the `@nodejs/doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better.
## Table of Contents
@@ -29,7 +29,7 @@ Thank you for your interest in contributing to the `@node-core/doc-kit` project!
## Getting Started
-The steps below will give you a general idea of how to prepare your local environment for the `@node-core/doc-kit` project and general steps for getting things done and landing your contribution.
+The steps below will give you a general idea of how to prepare your local environment for the `@nodejs/doc-kit` project and general steps for getting things done and landing your contribution.
### Prerequisites
@@ -77,7 +77,10 @@ This repository is an npm workspaces monorepo. The root package is private and
holds the shared tooling (linting, formatting, tests, changesets); every
published package lives under `packages/`:
-- `packages/core`: [`@node-core/doc-kit`](packages/core)
+- `packages/core`: [`@nodejs/doc-kit`](packages/core) — the doc-kit engine and CLI
+- `packages/legacy`: [`@nodejs/doc-kit-generator-legacy`](packages/legacy) — the legacy-format generators
+- `packages/node`: [`@node-core/doc-kit`](packages/node) — the Node.js-specific generators
+- `packages/react`: [`@nodejs/doc-kit-generator-react`](packages/react) — the React/JSX-based generators
Everything else at the root supports the repo rather than shipping to npm:
`docs/` (the reference docs), `www/` (the documentation site), `scripts/` (build
@@ -357,7 +360,7 @@ version in `package.json`, and writes the corresponding `CHANGELOG.md` entries.
To ship a release, a maintainer merges that "Version Packages" PR. The same workflow then:
-- publishes `@node-core/doc-kit` to npm (via [npm trusted publishing][] — no token required),
+- publishes the workspace packages to npm (via [npm trusted publishing][] — no token required),
- creates the matching `v` git tag, and
- cuts a GitHub Release from the changelog.
diff --git a/README.md b/README.md
index 1bcadb89..7a35a8ab 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
- @node-core/doc-kit is a tool to generate API documentation of Node.js. See this issue for more information.
+ @nodejs/doc-kit is a tool to generate API documentation of Node.js. See this issue for more information.
@@ -44,20 +44,40 @@ $ node packages/core/bin/cli.mjs --help
```
```
-Usage: @node-core/doc-kit [options] [command]
+Usage: @nodejs/doc-kit [options] [command]
-CLI tool to generate the Node.js API documentation
+CLI tool to generate API documentation
Options:
- --log-level Log level (choices: "debug", "info", "warn", "error",
- "fatal", default: "info")
- -h, --help display help for command
+ --log-level Log level (choices: "debug", "info",
+ "warn", "error", "fatal", default: "info")
+ -h, --help display help for command
Commands:
- generate [options] Generate API docs
- help [command] display help for command
+ generate [options] Generate API docs
+ install [options] [generators...] Install the packages providing built-in
+ generators (defaults to the targets in your
+ configuration file)
+ serve [options] Generate API docs, serve them locally, and
+ regenerate on changes
+ help [command] display help for command
```
+### `bootstrap`
+
+The fastest way to adopt doc-kit in a project:
+
+```sh
+npx doc-kit bootstrap
+npx doc-kit serve
+```
+
+`bootstrap` writes a `doc-kit.config.mjs` wired to your `package.json`
+(naming, versioning, homepage), finds or creates your documentation
+directory, ignores the output directory, and installs the packages for the
+generators you pick. `serve` then gives you a live-reloading preview while
+you write.
+
### `generate`
You must provide an input and at least one target through command-line options
@@ -67,7 +87,7 @@ Running `generate` without the required values exits with an error pointing you
to the help output.
```
-Usage: @node-core/doc-kit generate [options]
+Usage: @nodejs/doc-kit generate [options]
Generate API docs
@@ -78,14 +98,14 @@ Options:
(json-simple, legacy-html, legacy-html-all,
man-page, legacy-json, legacy-json-all,
addon-verify, api-links, orama-db, llms-txt,
- sitemap, web) or an import specifier for a custom
- generator
+ sitemap, html) or an import specifier for a
+ custom generator
--ignore Ignore file patterns (glob)
-o, --output The output directory
-p, --threads Number of threads to use (minimum: 1)
--chunk-size Number of items to process per worker thread
(minimum: 1)
- -v, --version Target Node.js version
+ -v, --version Target project version
-c, --changelog Changelog URL or path
--git-ref [ Git ref
--index index.md URL or path
@@ -94,6 +114,48 @@ Options:
-h, --help display help for command
```
+The defaults are project-neutral. To produce output styled and structured the
+way [nodejs.org](https://nodejs.org) builds its API docs, extend the Node.js
+preset in your configuration file — see
+[the configuration guide](docs/configuration.md#extending-presets):
+
+```mjs
+export default {
+ extends: '@node-core/doc-kit/config',
+};
+```
+
+### `install`
+
+Built-in generators live in separate packages. `install` adds the packages
+providing the given generators, using the package manager your lockfile
+indicates:
+
+```sh
+npx doc-kit install html orama-db
+```
+
+Without arguments, it installs whatever the `target` in your configuration
+file needs.
+
+### `serve`
+
+`serve` accepts the same options as `generate`, plus a `--port`. It generates
+the documentation, serves the output on (or the next
+available port), and regenerates whenever the input files change — ideal while
+writing documentation.
+
+```sh
+npx doc-kit serve -t html -i "docs/*.md" -o out
+```
+
+To serve an already-generated output directory without regenerating or
+watching, pass `--static`:
+
+```sh
+npx doc-kit serve --static -o out
+```
+
## Examples
### Legacy
@@ -111,11 +173,11 @@ npx doc-kit generate \
### Redesigned
-To generate [our redesigned documentation pages](https://nodejs-api-docs-tooling.vercel.app), use the `web` and `orama-db` (for search) generators.
+To generate [our redesigned documentation pages](https://nodejs-api-docs-tooling.vercel.app), use the `html` and `orama-db` (for search) generators. These generators live in the separate [`@nodejs/doc-kit-generator-react`](packages/react) package, which must be installed alongside this one.
```sh
npx doc-kit generate \
- -t web \
+ -t html \
-t orama-db \
-i "path/to/node/doc/api/*.md" \
-o out \
@@ -126,5 +188,5 @@ npx doc-kit generate \
> In order to use the search functionality, you _must_ serve the output directory.
>
> ```sh
-> npx serve out
+> npx doc-kit serve --static -o out
> ```
diff --git a/beta/doc-kit.config.mjs b/beta/doc-kit.config.mjs
index 07484c9c..13d2b824 100644
--- a/beta/doc-kit.config.mjs
+++ b/beta/doc-kit.config.mjs
@@ -1,5 +1,7 @@
export default {
- web: {
+ extends: '@node-core/doc-kit/config',
+
+ html: {
remoteConfigUrl:
'https://raw.githubusercontent.com/nodejs/doc-kit/main/beta/site.json',
diff --git a/docs/comparators.md b/docs/comparators.md
index 6f87f379..1cafcd52 100644
--- a/docs/comparators.md
+++ b/docs/comparators.md
@@ -1,6 +1,6 @@
# Creating Comparators
-This guide explains how to create build comparison scripts for `@node-core/doc-kit`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing.
+This guide explains how to create build comparison scripts for `@nodejs/doc-kit`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing.
## Comparator Concepts
@@ -35,7 +35,7 @@ scripts/comparators/
Comparators can be reused across multiple generators. You specify which comparator to use in the workflow file using the `compare` field. For example:
-- `file-size.mjs` can compare output from `web`, `legacy-html`, or any generator
+- `file-size.mjs` can compare output from `html`, `legacy-html`, or any generator
- `object-assertion.mjs` can compare JSON output from `legacy-json`, `json-simple`, etc.
- `my-comparator.mjs` would be a custom comparator for specific needs
diff --git a/docs/configuration.md b/docs/configuration.md
index eef68555..7ed61054 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -39,7 +39,7 @@ export default {
// Targets, alternatively supplied by command line flags. Each entry is
// either a built-in shorthand name or an import specifier resolving to a
// generator module (e.g. '@my-scope/my-package/my-generator').
- target: ['orama-db', 'web'],
+ target: ['orama-db', 'html'],
global: {
version: '20.0.0',
minify: true,
@@ -114,6 +114,34 @@ export default {
};
```
+## Extending Presets
+
+A configuration file may declare `extends`: one or more presets whose values
+are merged underneath its own. Each entry is either an import specifier of a
+module whose default export is a configuration object, or a path relative to
+the configuration file:
+
+```mjs
+export default {
+ // Build the docs the way nodejs.org does — branding, URL layouts,
+ // and release history included
+ extends: '@node-core/doc-kit/config',
+
+ html: {
+ // Your own values still win over the preset
+ title: '{project} {version} API Reference',
+ },
+};
+```
+
+`extends` also accepts an array; later presets take precedence over earlier
+ones, and the configuration file itself wins over all of them.
+
+The built-in defaults are deliberately project-neutral: no repository,
+site URL, release history, or branding is assumed. The
+[`@node-core/doc-kit/config`](https://github.com/nodejs/doc-kit/tree/main/packages/node)
+preset opts back into everything Node.js-specific.
+
## Configuration Merging
Configurations are merged in the following order (higher sources take
@@ -121,7 +149,8 @@ precedence):
1. **CLI options** (command-line arguments)
2. **Configuration file** (discovered or selected with `--config-file`)
-3. **Default values** (built-in defaults)
+3. **Presets** (listed in the configuration file's `extends`)
+4. **Default values** (built-in defaults)
## CLI Options Mapping
diff --git a/docs/generators.md b/docs/generators.md
index 33f02c02..a3907501 100644
--- a/docs/generators.md
+++ b/docs/generators.md
@@ -1,6 +1,6 @@
# Creating Generators
-This guide explains how to create new documentation generators for `@node-core/doc-kit`.
+This guide explains how to create new documentation generators for `@nodejs/doc-kit`.
## Generator Concepts
@@ -21,7 +21,7 @@ Raw Markdown Files
↓
[jsx-ast] - Convert to JSX AST
↓
- [web] - Generate HTML/CSS/JS bundles
+ [html] - Generate HTML/CSS/JS bundles
```
Each generator declares its dependency using the `dependsOn` field, allowing automatic pipeline construction.
@@ -88,7 +88,7 @@ export default {
// This generator depends on the metadata generator. Dependencies are
// declared as import specifiers, so they can live in any package.
- dependsOn: '@node-core/doc-kit/metadata',
+ dependsOn: '@nodejs/doc-kit/metadata',
defaultConfiguration: {
// If your generator supports a custom configuration, define the defaults here
@@ -170,8 +170,8 @@ the import specifier it resolves to:
```javascript
export const publicGenerators = {
- 'json-simple': '@node-core/doc-kit/json-simple',
- 'my-format': '@node-core/doc-kit/my-format', // Add this
+ 'json-simple': '@nodejs/doc-kit/json-simple',
+ 'my-format': '@nodejs/doc-kit/my-format', // Add this
// ... other generators
};
```
@@ -199,7 +199,7 @@ export default {
description: 'Processes data in parallel',
- dependsOn: '@node-core/doc-kit/metadata',
+ dependsOn: '@nodejs/doc-kit/metadata',
// Indicates this generator has a processChunk implementation
hasParallelProcessor: true,
@@ -296,7 +296,7 @@ export default {
description: 'Streams results as they are ready',
- dependsOn: '@node-core/doc-kit/metadata',
+ dependsOn: '@nodejs/doc-kit/metadata',
hasParallelProcessor: true,
@@ -357,7 +357,7 @@ export default {
description: 'Requires all input at once',
- dependsOn: '@node-core/doc-kit/jsx-ast',
+ dependsOn: '@nodejs/doc-kit-generator-react/jsx-ast',
generate,
};
@@ -403,7 +403,7 @@ export default {
// This generator requires the metadata generator's output. The dependency
// is an import specifier, so it may point at any installed package.
- dependsOn: '@node-core/doc-kit/metadata',
+ dependsOn: '@nodejs/doc-kit/metadata',
// ... other metadata
@@ -434,7 +434,7 @@ export default {
// packages/core/src/generators/metadata/index.mjs
export default {
name: 'metadata',
- dependsOn: '@node-core/doc-kit/ast', // Depends on AST
+ dependsOn: '@nodejs/doc-kit/ast', // Depends on AST
// Processes AST output
};
@@ -442,7 +442,7 @@ export default {
// packages/core/src/generators/html-generator/index.mjs
export default {
name: 'html-generator',
- dependsOn: '@node-core/doc-kit/metadata', // Depends on metadata
+ dependsOn: '@nodejs/doc-kit/metadata', // Depends on metadata
// Processes metadata output
};
```
diff --git a/docs/specification.md b/docs/specification.md
index 1012e49f..a1f75ad5 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -5,7 +5,7 @@
**Authored By**: Aviv Keller ()
This document specifies the Markdown format consumed by
-[`@node-core/doc-kit`][doc-kit]. It defines the structural, syntactic, and
+[`@nodejs/doc-kit`][doc-kit]. It defines the structural, syntactic, and
semantic rules that documents MUST follow to be correctly parsed. The format
is a strict superset of [GitHub Flavored Markdown][gfm] (which itself is a
strict superset of [CommonMark][commonmark]), adding conventions for API
diff --git a/e2e/doc-kit.config.mjs b/e2e/doc-kit.config.mjs
new file mode 100644
index 00000000..9db34eb8
--- /dev/null
+++ b/e2e/doc-kit.config.mjs
@@ -0,0 +1,3 @@
+export default {
+ extends: '@node-core/doc-kit/config',
+};
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 197acf57..5f890af3 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -13,7 +13,7 @@ export default defineConfig([
ignores: [
'www/out',
'out/',
- 'packages/core/src/generators/api-links/__tests__/fixtures/',
+ 'packages/node/src/api-links/__tests__/fixtures/',
],
},
{
@@ -95,8 +95,8 @@ export default defineConfig([
},
{
files: [
- 'packages/core/src/generators/legacy-html/assets/*.js',
- 'packages/core/src/generators/web/ui/**/*',
+ 'packages/legacy/src/legacy-html/assets/*.js',
+ 'packages/react/src/html/ui/**/*',
],
languageOptions: {
globals: {
diff --git a/package-lock.json b/package-lock.json
index 3a8ce0c9..c03f0780 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,11 +1,11 @@
{
- "name": "@node-core/doc-kit-monorepo",
+ "name": "@nodejs/doc-kit-monorepo",
"version": "1.4.3",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
- "name": "@node-core/doc-kit-monorepo",
+ "name": "@nodejs/doc-kit-monorepo",
"workspaces": [
"packages/*"
],
@@ -1328,7 +1328,7 @@
}
},
"node_modules/@node-core/doc-kit": {
- "resolved": "packages/core",
+ "resolved": "packages/node",
"link": true
},
"node_modules/@node-core/rehype-shiki": {
@@ -1387,6 +1387,18 @@
"node": ">=20"
}
},
+ "node_modules/@nodejs/doc-kit": {
+ "resolved": "packages/core",
+ "link": true
+ },
+ "node_modules/@nodejs/doc-kit-generator-legacy": {
+ "resolved": "packages/legacy",
+ "link": true
+ },
+ "node_modules/@nodejs/doc-kit-generator-react": {
+ "resolved": "packages/react",
+ "link": true
+ },
"node_modules/@nodelib/fs.scandir": {
"version": "2.1.5",
"resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
@@ -11202,38 +11214,21 @@
}
},
"packages/core": {
- "name": "@node-core/doc-kit",
- "version": "1.4.3",
+ "name": "@nodejs/doc-kit",
+ "version": "0.0.0",
"dependencies": {
- "@11ty/is-land": "^5.0.1",
"@actions/core": "^3.0.0",
- "@fontsource-variable/open-sans": "^5.3.0",
- "@fontsource/ibm-plex-mono": "^5.3.0",
- "@heroicons/react": "^2.2.0",
"@node-core/rehype-shiki": "^1.4.3",
- "@node-core/ui-components": "^1.7.4",
- "@orama/orama": "^3.1.18",
- "@orama/ui": "^1.5.4",
"@swc/html-wasm": "^1.15.46",
"@swc/wasm": "^1.15.46",
"acorn": "^8.17.0",
"commander": "^15.0.0",
"cosmiconfig": "^9.0.2",
"dedent": "^1.7.2",
- "estree-util-to-js": "^2.0.0",
- "estree-util-visit": "^2.0.0",
"github-slugger": "^2.0.0",
"glob-parent": "^6.0.2",
- "hast-util-to-string": "^3.0.1",
"hastscript": "^9.0.1",
- "mdast-util-slice-markdown": "^2.0.1",
"piscina": "^5.3.0",
- "preact": "^10.29.7",
- "preact-render-to-string": "^6.7.0",
- "reading-time": "^1.5.0",
- "recma-jsx": "^1.0.1",
- "rehype-raw": "^7.0.0",
- "rehype-recma": "^1.0.0",
"rehype-stringify": "^10.0.1",
"remark-gfm": "^4.0.1",
"remark-mdx": "^3.1.1",
@@ -11250,11 +11245,79 @@
"unist-util-remove": "^4.0.0",
"unist-util-select": "^5.1.0",
"unist-util-visit": "^5.1.0",
- "vite": "~8.1.5",
"yaml": "^2.9.0"
},
"bin": {
"doc-kit": "bin/cli.mjs"
+ },
+ "peerDependencies": {
+ "@node-core/doc-kit": "^1.4.3",
+ "@nodejs/doc-kit-generator-legacy": "^0.0.0",
+ "@nodejs/doc-kit-generator-react": "^0.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@node-core/doc-kit": {
+ "optional": true
+ },
+ "@nodejs/doc-kit-generator-legacy": {
+ "optional": true
+ },
+ "@nodejs/doc-kit-generator-react": {
+ "optional": true
+ }
+ }
+ },
+ "packages/legacy": {
+ "name": "@nodejs/doc-kit-generator-legacy",
+ "version": "0.0.0",
+ "dependencies": {
+ "@nodejs/doc-kit": "^0.0.0",
+ "hastscript": "^9.0.1",
+ "unist-builder": "^4.0.0",
+ "unist-util-visit": "^5.1.0"
+ }
+ },
+ "packages/node": {
+ "name": "@node-core/doc-kit",
+ "version": "1.4.3",
+ "dependencies": {
+ "@nodejs/doc-kit": "^0.0.0",
+ "dedent": "^1.7.2",
+ "estree-util-visit": "^2.0.0",
+ "unist-util-visit": "^5.1.0"
+ }
+ },
+ "packages/react": {
+ "name": "@nodejs/doc-kit-generator-react",
+ "version": "0.0.0",
+ "dependencies": {
+ "@11ty/is-land": "^5.0.1",
+ "@fontsource-variable/open-sans": "^5.3.0",
+ "@fontsource/ibm-plex-mono": "^5.3.0",
+ "@heroicons/react": "^2.2.0",
+ "@node-core/rehype-shiki": "^1.4.3",
+ "@node-core/ui-components": "^1.7.4",
+ "@nodejs/doc-kit": "^0.0.0",
+ "@orama/orama": "^3.1.18",
+ "@orama/ui": "^1.5.4",
+ "estree-util-to-js": "^2.0.0",
+ "hast-util-to-string": "^3.0.1",
+ "hastscript": "^9.0.1",
+ "mdast-util-slice-markdown": "^2.0.1",
+ "preact": "^10.29.7",
+ "preact-render-to-string": "^6.7.0",
+ "reading-time": "^1.5.0",
+ "recma-jsx": "^1.0.1",
+ "recma-stringify": "^1.0.0",
+ "rehype-raw": "^7.0.0",
+ "rehype-recma": "^1.0.0",
+ "remark-parse": "^11.0.0",
+ "remark-rehype": "^11.1.2",
+ "semver": "^7.8.5",
+ "unified": "^11.0.5",
+ "unist-builder": "^4.0.0",
+ "unist-util-visit": "^5.1.0",
+ "vite": "~8.1.5"
}
}
}
diff --git a/package.json b/package.json
index d868527f..5bb1e54f 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
{
- "name": "@node-core/doc-kit-monorepo",
+ "name": "@nodejs/doc-kit-monorepo",
"private": true,
"type": "module",
"workspaces": [
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
index d326689b..92a34618 100644
--- a/packages/core/CHANGELOG.md
+++ b/packages/core/CHANGELOG.md
@@ -1,4 +1,4 @@
-# @node-core/doc-kit
+# @nodejs/doc-kit
## 1.4.3
diff --git a/packages/core/README.md b/packages/core/README.md
index 30c43306..3e26f00a 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,4 +1,4 @@
-# `@node-core/doc-kit`
+# `@nodejs/doc-kit`
The core of doc-kit: the CLI and the generators that turn API-shaped Markdown
into HTML, JSON, man pages and more.
@@ -10,7 +10,7 @@ references.
## Scripts
Run these from this directory, or from the repository root with
-`npm run
-
-
-
-
- ]${dehydrated}
-
-
-