diff --git a/docs/specification.md b/docs/specification.md
index 7ff09cb3..1012e49f 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -19,110 +19,6 @@ meaning by this specification (e.g., blockquotes as stability indicators,
unordered lists as typed parameter lists), that special meaning is documented
in the relevant section.
-## Table of Contents
-
-- [1. Terminology and Conventions](#1-terminology-and-conventions)
- - [1.1. Requirement Level Keywords](#11-requirement-level-keywords)
- - [1.2. Definitions](#12-definitions)
-- [2. Conformance](#2-conformance)
- - [2.1. Base Grammar](#21-base-grammar)
- - [2.2. Character Encoding](#22-character-encoding)
- - [2.3. Line Endings](#23-line-endings)
- - [2.4. Whitespace](#24-whitespace)
-- [3. Document Structure](#3-document-structure)
- - [3.1. Top-Level Ordering](#31-top-level-ordering)
- - [3.2. Entry Ordering](#32-entry-ordering)
-- [4. Headings](#4-headings)
- - [4.1. Style](#41-style)
- - [4.2. Depth Semantics](#42-depth-semantics)
- - [4.2.1. Depth 1](#421-depth-1)
- - [4.2.2. Depth 2](#422-depth-2)
- - [4.2.3. Additional Depths](#423-additional-depths)
- - [4.3. Entry Type Classification](#43-entry-type-classification)
- - [4.3.1. Method](#431-method)
- - [4.3.2. Event](#432-event)
- - [4.3.3. Class](#433-class)
- - [4.3.4. Constructor](#434-constructor)
- - [4.3.5. Static Method](#435-static-method)
- - [4.3.6. Property](#436-property)
- - [4.3.7. Default Classification](#437-default-classification)
- - [4.4. Document Type and Heading Interpretation](#44-document-type-and-heading-interpretation)
- - [4.4.1. Module Documents](#441-module-documents)
- - [4.4.2. Miscellaneous Documents](#442-miscellaneous-documents)
- - [4.4.3. Global Documents](#443-global-documents)
- - [4.4.4. Module Context Override](#444-module-context-override)
- - [4.4.5. Per-Entry Override](#445-per-entry-override)
- - [4.5. Heading Text Conventions](#45-heading-text-conventions)
- - [4.5.1. Code Spans in Headings](#451-code-spans-in-headings)
- - [4.5.2. Event Name Quoting](#452-event-name-quoting)
- - [4.5.3. Multiple Forms](#453-multiple-forms)
-- [5. Signature Syntax](#5-signature-syntax)
- - [5.1. Required Parameters](#51-required-parameters)
- - [5.2. Optional Parameters](#52-optional-parameters)
- - [5.3. Nested Optionals](#53-nested-optionals)
- - [5.4. Rest Parameters](#54-rest-parameters)
- - [5.5. Constraints](#55-constraints)
-- [6. YAML Comment Blocks](#6-yaml-comment-blocks)
- - [6.1. Block Syntax](#61-block-syntax)
- - [6.2. Simple Directives](#62-simple-directives)
- - [6.2.1. `introduced_in`](#621-introduced_in)
- - [6.2.2. `type`](#622-type)
- - [6.2.3. `source_link`](#623-source_link)
- - [6.2.4. `llm_description`](#624-llm_description)
- - [6.2.5. `module`](#625-module)
- - [6.3. YAML Metadata Fields](#63-yaml-metadata-fields)
- - [6.3.1. `added`](#631-added)
- - [6.3.2. `deprecated`](#632-deprecated)
- - [6.3.3. `removed`](#633-removed)
- - [6.3.4. `changes`](#634-changes)
- - [6.3.5. `type` (Override)](#635-type-override)
- - [6.3.6. `source_link`](#636-source_link)
- - [6.3.7. `llm_description`](#637-llm_description)
- - [6.4. Version Strings](#64-version-strings)
- - [6.5. Plain Tag Comments](#65-plain-tag-comments)
- - [6.6. Frontmatter Conversion](#66-frontmatter-conversion)
- - [6.7. Placement](#67-placement)
-- [7. Stability Indicators](#7-stability-indicators)
- - [7.1. Syntax](#71-syntax)
- - [7.2. Levels](#72-levels)
- - [7.2.1. Level 0 - Deprecated](#721-level-0--deprecated)
- - [7.2.2. Level 1 - Experimental](#722-level-1--experimental)
- - [7.2.3. Level 2 - Stable](#723-level-2--stable)
- - [7.2.4. Level 3 - Legacy](#724-level-3--legacy)
- - [7.3. Sub-Levels](#73-sub-levels)
- - [7.3.1. 1.0 - Early Development](#731-10--early-development)
- - [7.3.2. 1.1 - Active Development](#732-11--active-development)
- - [7.3.3. 1.2 - Release Candidate](#733-12--release-candidate)
- - [7.4. Multi-Line Indicators](#74-multi-line-indicators)
- - [7.5. Inline Content](#75-inline-content)
- - [7.6. Placement](#76-placement)
-- [8. Type Annotations](#8-type-annotations)
- - [8.1. Syntax](#81-syntax)
- - [8.2. Parsing](#82-parsing)
- - [8.3. Resolution](#83-resolution)
- - [8.4. Rendering](#84-rendering)
-- [9. Typed Parameter Lists](#9-typed-parameter-lists)
- - [9.1. Identification](#91-identification)
- - [9.2. Item Structure](#92-item-structure)
- - [9.3. Special Prefixes](#93-special-prefixes)
- - [9.3.1. `Returns:`](#931-returns)
- - [9.3.2. `Extends:`](#932-extends)
- - [9.3.3. `Type:`](#933-type)
- - [9.4. Nested Properties](#94-nested-properties)
- - [9.5. Default Values](#95-default-values)
- - [9.6. Placement](#96-placement)
-- [10. Code Blocks](#10-code-blocks)
- - [10.1. Fence Style](#101-fence-style)
- - [10.2. Info Strings](#102-info-strings)
- - [10.3. The `displayName` Attribute](#103-the-displayname-attribute)
-- [11. Links and Cross-References](#11-links-and-cross-references)
- - [11.1. Reference-Style Links](#111-reference-style-links)
- - [11.2. Cross-Document Links](#112-cross-document-links)
- - [11.3. External Links](#113-external-links)
- - [11.4. System-Call Auto-Linking](#114-system-call-auto-linking)
- - [11.5. Type Auto-Linking](#115-type-auto-linking)
- - [11.6. Link Reference Definitions](#116-link-reference-definitions)
-
---
## 1. Terminology and Conventions
diff --git a/packages/core/src/generators/addon-verify/README.md b/packages/core/src/generators/addon-verify/README.md
index 34815ddb..b6f681bb 100644
--- a/packages/core/src/generators/addon-verify/README.md
+++ b/packages/core/src/generators/addon-verify/README.md
@@ -4,8 +4,4 @@ The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and g
## Configuring
-The `addon-verify` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | -------- | ------- | -------------------------------------------------------- |
-| `output` | `string` | - | The directory where extracted code files will be written |
+- `output` {string} The directory where extracted code files will be written.
diff --git a/packages/core/src/generators/api-links/README.md b/packages/core/src/generators/api-links/README.md
index fa4d44d0..fed3884e 100644
--- a/packages/core/src/generators/api-links/README.md
+++ b/packages/core/src/generators/api-links/README.md
@@ -4,10 +4,8 @@ The `api-links` generator creates a mapping of publicly accessible functions to
## Configuring
-The `api-links` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ----------- | --------- | ------------------------------------ | --------------------------------------------------- |
-| `output` | `string` | - | The directory where `apilinks.json` will be written |
-| `sourceURL` | `string` | `'${GITHUB_BLOB_URL}lib/{fileName}'` | URL template for linking to source files |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
+- `output` {string} The directory where `apilinks.json` will be written.
+- `sourceURL` {string} URL template for linking to source files.
+ **Default:** `'${GITHUB_BLOB_URL}lib/{fileName}'`.
+- `minify` {boolean} Whether to minify the output JSON. Inherited from
+ `global`. **Default:** `true`.
diff --git a/packages/core/src/generators/ast-js/README.md b/packages/core/src/generators/ast-js/README.md
index a6b7b74c..fd4857ed 100644
--- a/packages/core/src/generators/ast-js/README.md
+++ b/packages/core/src/generators/ast-js/README.md
@@ -4,9 +4,5 @@ The `ast-js` generator parses JavaScript source files into AST (Abstract Syntax
## Configuring
-The `ast-js` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | -------------------- | ------- | ------------------------------------------------- |
-| `input` | `string \| string[]` | - | Glob pattern(s) for the JavaScript files to parse |
-| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
+- `input` {string|string[]} Glob pattern(s) for the JavaScript files to parse.
+- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.
diff --git a/packages/core/src/generators/ast/README.md b/packages/core/src/generators/ast/README.md
index 47531bd1..192236bc 100644
--- a/packages/core/src/generators/ast/README.md
+++ b/packages/core/src/generators/ast/README.md
@@ -4,9 +4,5 @@ The `ast` generator parses Markdown API documentation files into AST (Abstract S
## Configuring
-The `ast` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | -------------------- | ------- | ------------------------------------------------- |
-| `input` | `string \| string[]` | - | Glob pattern(s) for the Markdown files to parse |
-| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
+- `input` {string|string[]} Glob pattern(s) for the Markdown files to parse.
+- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.
diff --git a/packages/core/src/generators/json-simple/README.md b/packages/core/src/generators/json-simple/README.md
index c75e2f71..f052adcb 100644
--- a/packages/core/src/generators/json-simple/README.md
+++ b/packages/core/src/generators/json-simple/README.md
@@ -4,9 +4,6 @@ The `json-simple` generator creates a simplified JSON version of the API documen
## Configuring
-The `json-simple` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | --------- | ----------------------- | --------------------------------------------------- |
-| `output` | `string` | - | The directory where `api-docs.json` will be written |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
+- `output` {string} The directory where `api-docs.json` will be written.
+- `minify` {boolean} Whether to minify the output JSON. Inherited from
+ `global`. **Default:** `true`.
diff --git a/packages/core/src/generators/jsx-ast/README.md b/packages/core/src/generators/jsx-ast/README.md
index e677bc73..e4f95dba 100644
--- a/packages/core/src/generators/jsx-ast/README.md
+++ b/packages/core/src/generators/jsx-ast/README.md
@@ -4,12 +4,13 @@ The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AS
## Configuring
-The `jsx-ast` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ---------------------- | --------- | -------- | ------------------------------------------------------------------------ |
-| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
-| `index` | `array` | - | Array of `{ section, api }` objects defining the documentation structure |
-| `generateAllPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `all.html` |
-| `generateIndexPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `index.html` |
-| `generateNotFoundPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `404.html` |
+- `ref` {string} Git reference/branch for linking to source files.
+ **Default:** `'main'`.
+- `index` {Array} Array of `{ section, api }` objects defining the
+ documentation structure.
+- `generateAllPage` {boolean} When `true`, creates a synthetic JSX AST entry
+ for `all.html`. **Default:** `true`.
+- `generateIndexPage` {boolean} When `true`, creates a synthetic JSX AST entry
+ for `index.html`. **Default:** `true`.
+- `generateNotFoundPage` {boolean} When `true`, creates a synthetic JSX AST
+ entry for `404.html`. **Default:** `true`.
diff --git a/packages/core/src/generators/legacy-html-all/README.md b/packages/core/src/generators/legacy-html-all/README.md
index 7ba00961..d854ea1e 100644
--- a/packages/core/src/generators/legacy-html-all/README.md
+++ b/packages/core/src/generators/legacy-html-all/README.md
@@ -4,11 +4,10 @@ The `legacy-html-all` generator creates a single `all.html` file containing all
## Configuring
-The `legacy-html-all` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------------- | --------- | ---------------------------- | ---------------------------------------------- |
-| `output` | `string` | - | The directory where `all.html` will be written |
-| `templatePath` | `string` | Inherited from `legacy-html` | Path to the HTML template file |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
-| `version` | `object` | Inherited from `global` | Version object containing version information |
+- `output` {string} The directory where `all.html` will be written.
+- `templatePath` {string} Path to the HTML template file. Inherited from
+ `legacy-html`. **Default:** `'template.html'`.
+- `minify` {boolean} Whether to minify the output HTML. Inherited from
+ `global`. **Default:** `true`.
+- `version` {Object} Version object containing version information. Inherited
+ from `global`. **Default:** `process.version`.
diff --git a/packages/core/src/generators/legacy-html/README.md b/packages/core/src/generators/legacy-html/README.md
index 6f007d78..da7a9552 100644
--- a/packages/core/src/generators/legacy-html/README.md
+++ b/packages/core/src/generators/legacy-html/README.md
@@ -4,15 +4,18 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js
## Configuring
-The `legacy-html` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ----------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------ |
-| `output` | `string` | - | The directory where HTML files and assets will be written |
-| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
-| `additionalPathsToCopy` | `string[]` | `['assets']` | Array of paths to copy to the output directory |
-| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
-| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
-| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
-| `index` | `array` | - | Array of `{ api, section }` objects defining the documentation structure |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
+- `output` {string} The directory where HTML files and assets will be written.
+- `templatePath` {string} Path to the HTML template file.
+ **Default:** `'template.html'`.
+- `additionalPathsToCopy` {string[]} Array of paths to copy to the output
+ directory. **Default:** `['assets']`.
+- `ref` {string} Git reference/branch for linking to source files.
+ **Default:** `'main'`.
+- `pageURL` {string} URL template for documentation page links.
+ **Default:** `'{baseURL}/latest-{version}/api{path}.html'`.
+- `editURL` {string} URL template for "edit this page" links.
+ **Default:** `'${GITHUB_EDIT_URL}/doc/api{path}.md'`.
+- `index` {Array} Array of `{ api, section }` objects defining the
+ documentation structure.
+- `minify` {boolean} Whether to minify the output HTML. Inherited from
+ `global`. **Default:** `true`.
diff --git a/packages/core/src/generators/legacy-json-all/README.md b/packages/core/src/generators/legacy-json-all/README.md
index 2c09b212..cde77e9d 100644
--- a/packages/core/src/generators/legacy-json-all/README.md
+++ b/packages/core/src/generators/legacy-json-all/README.md
@@ -4,10 +4,6 @@ The `legacy-json-all` generator consolidates data from the `legacy-json` generat
## Configuring
-The `legacy-json-all` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | --------- | ------- | ---------------------------------------------------- |
-| `output` | `string` | - | The directory where `all.json` will be written |
-| `minify` | `boolean` | `false` | Whether to minify the output JSON |
-| `index` | `array` | - | Array of `{ api }` objects defining the module order |
+- `output` {string} The directory where `all.json` will be written.
+- `minify` {boolean} Whether to minify the output JSON. **Default:** `false`.
+- `index` {Array} Array of `{ api }` objects defining the module order.
diff --git a/packages/core/src/generators/legacy-json/README.md b/packages/core/src/generators/legacy-json/README.md
index ffd71573..476522f4 100644
--- a/packages/core/src/generators/legacy-json/README.md
+++ b/packages/core/src/generators/legacy-json/README.md
@@ -4,10 +4,7 @@ The `legacy-json` generator creates legacy JSON files for the API documentation
## Configuring
-The `legacy-json` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | --------- | -------- | ------------------------------------------------ |
-| `output` | `string` | - | The directory where JSON files will be written |
-| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
-| `minify` | `boolean` | `false` | Whether to minify the output JSON |
+- `output` {string} The directory where JSON files will be written.
+- `ref` {string} Git reference/branch for linking to source files.
+ **Default:** `'main'`.
+- `minify` {boolean} Whether to minify the output JSON. **Default:** `false`.
diff --git a/packages/core/src/generators/llms-txt/README.md b/packages/core/src/generators/llms-txt/README.md
index e8eb1f67..651bc725 100644
--- a/packages/core/src/generators/llms-txt/README.md
+++ b/packages/core/src/generators/llms-txt/README.md
@@ -4,10 +4,8 @@ The `llms-txt` generator creates a `llms.txt` file to provide information to Lar
## Configuring
-The `llms-txt` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------------- | -------- | --------------------------------- | ---------------------------------------------- |
-| `output` | `string` | - | The directory where `llms.txt` will be written |
-| `templatePath` | `string` | `'template.txt'` | Path to the template file |
-| `pageURL` | `string` | `'{baseURL}/latest/api{path}.md'` | URL template for documentation page links |
+- `output` {string} The directory where `llms.txt` will be written.
+- `templatePath` {string} Path to the template file.
+ **Default:** `'template.txt'`.
+- `pageURL` {string} URL template for documentation page links.
+ **Default:** `'{baseURL}/latest/api{path}.md'`.
diff --git a/packages/core/src/generators/man-page/README.md b/packages/core/src/generators/man-page/README.md
index 4448bf9a..ae7cc52e 100644
--- a/packages/core/src/generators/man-page/README.md
+++ b/packages/core/src/generators/man-page/README.md
@@ -4,12 +4,11 @@ The `man-page` generator creates a Unix man page version of the Node.js CLI docu
## Configuring
-The `man-page` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ---------------------- | -------- | --------------------------- | ----------------------------------------------------- |
-| `output` | `string` | - | The directory where the man page file will be written |
-| `fileName` | `string` | `'node.1'` | Name of the output file |
-| `cliOptionsHeaderSlug` | `string` | `'options'` | Slug for the CLI options header section |
-| `envVarsHeaderSlug` | `string` | `'environment-variables-1'` | Slug for the environment variables header section |
-| `templatePath` | `string` | `'template.1'` | Path to the man page template file |
+- `output` {string} The directory where the man page file will be written.
+- `fileName` {string} Name of the output file. **Default:** `'node.1'`.
+- `cliOptionsHeaderSlug` {string} Slug for the CLI options header section.
+ **Default:** `'options'`.
+- `envVarsHeaderSlug` {string} Slug for the environment variables header
+ section. **Default:** `'environment-variables-1'`.
+- `templatePath` {string} Path to the man page template file.
+ **Default:** `'template.1'`.
diff --git a/packages/core/src/generators/metadata/README.md b/packages/core/src/generators/metadata/README.md
index e9ce8b84..1146e03b 100644
--- a/packages/core/src/generators/metadata/README.md
+++ b/packages/core/src/generators/metadata/README.md
@@ -4,8 +4,5 @@ The `metadata` generator creates a flattened list of metadata entries from API d
## Configuring
-The `metadata` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| --------- | -------- | ---------------- | -------------------------------------------------- |
-| `typeMap` | `string` | `'typeMap.json'` | URL or path to the type mapping configuration file |
+- `typeMap` {string} URL or path to the type mapping configuration file.
+ **Default:** `'typeMap.json'`.
diff --git a/packages/core/src/generators/orama-db/README.md b/packages/core/src/generators/orama-db/README.md
index 5ac0aa32..2b33f2c2 100644
--- a/packages/core/src/generators/orama-db/README.md
+++ b/packages/core/src/generators/orama-db/README.md
@@ -4,9 +4,6 @@ The `orama-db` generator creates an Orama database for the API documentation to
## Configuring
-The `orama-db` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| -------- | --------- | ----------------------- | --------------------------------------------------- |
-| `output` | `string` | - | The directory where `orama-db.json` will be written |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
+- `output` {string} The directory where `orama-db.json` will be written.
+- `minify` {boolean} Whether to minify the output JSON. Inherited from
+ `global`. **Default:** `true`.
diff --git a/packages/core/src/generators/sitemap/README.md b/packages/core/src/generators/sitemap/README.md
index 874d1a25..a0a3543e 100644
--- a/packages/core/src/generators/sitemap/README.md
+++ b/packages/core/src/generators/sitemap/README.md
@@ -4,10 +4,8 @@ The `sitemap` generator creates a `sitemap.xml` file for search engine optimizat
## Configuring
-The `sitemap` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ---------- | -------- | ------------------------- | ------------------------------------------------- |
-| `output` | `string` | - | The directory where `sitemap.xml` will be written |
-| `indexURL` | `string` | `'{baseURL}/latest/api/'` | URL template for the API documentation index page |
-| `pageURL` | `string` | `'{indexURL}{path}.html'` | URL template for individual documentation pages |
+- `output` {string} The directory where `sitemap.xml` will be written.
+- `indexURL` {string} URL template for the API documentation index page.
+ **Default:** `'{baseURL}/latest/api/'`.
+- `pageURL` {string} URL template for individual documentation pages.
+ **Default:** `'{indexURL}{path}.html'`.
diff --git a/packages/core/src/generators/web/README.md b/packages/core/src/generators/web/README.md
index f49f59fb..c86c521b 100644
--- a/packages/core/src/generators/web/README.md
+++ b/packages/core/src/generators/web/README.md
@@ -9,36 +9,48 @@ its HTML or CSS.
## Configuring
-The `web` generator accepts the following configuration options:
-
-| Name | Type | Default | Description |
-| ----------------- | ------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `output` | `string` | Required | The directory where HTML and bundled client output are written |
-| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
-| `project` | `string` | `'Node.js'` | Project name used in page titles and the version selector |
-| `title` | `string` | `'{project} v{version} Documentation'` | Title template for HTML pages (supports `{project}`, `{version}`) |
-| `useAbsoluteURLs` | `boolean` | `false` | When `true`, all internal links use absolute URLs based on `baseURL` |
-| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
-| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
-| `remoteConfigUrl` | `string` | `'https://nodejs.org/site.json'` | URL fetched client-side at runtime for remote site config (currently used to power the announcement banner) |
-| `head` | `object` | See below | Configurable ``, ``, and raw markup for the document head |
-| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization |
-| `virtualImports` | `object` | `{}` | Additional virtual module mappings supplied to the server and client builds |
-| `components` | `object` | `{}` | Maps JSX tag names to component imports, enabling JSX-in-MDX (see below) |
-| `navigation` | `object` | `{}` | Sidebar groups and navigation bar items (see below) |
-| `bundler` | `WebBundler` | Vite adapter | Adapter that renders server entries and writes the client and HTML output (see below) |
+- `output` {string} The directory where HTML and bundled client output are
+ written. Required.
+- `templatePath` {string} Path to the HTML template file.
+ **Default:** `'template.html'`.
+- `project` {string} Project name used in page titles and the version selector.
+ **Default:** `'Node.js'`.
+- `title` {string} Title template for HTML pages (supports `{project}`,
+ `{version}`). **Default:** `'{project} v{version} Documentation'`.
+- `useAbsoluteURLs` {boolean} When `true`, all internal links use absolute URLs
+ based on `baseURL`. **Default:** `false`.
+- `editURL` {string} URL template for "edit this page" links.
+ **Default:** `'${GITHUB_EDIT_URL}/doc/api{path}.md'`.
+- `pageURL` {string} URL template for documentation page links.
+ **Default:** `'{baseURL}/latest-{version}/api{path}.html'`.
+- `remoteConfigUrl` {string} URL fetched client-side at runtime for remote site
+ config (currently used to power the announcement banner).
+ **Default:** `'https://nodejs.org/site.json'`.
+- `head` {Object} Configurable ``, ``, and raw markup for the
+ document head. See [`head`](#head).
+- `imports` {Object} Object mapping `#theme/` aliases to component paths for
+ customization. See [Default `imports`](#default-imports).
+- `virtualImports` {Object} Additional virtual module mappings supplied to the
+ server and client builds. **Default:** `{}`.
+- `components` {Object} Maps JSX tag names to component imports, enabling
+ JSX-in-MDX. See [`components`](#components). **Default:** `{}`.
+- `navigation` {Object} Sidebar groups and navigation bar items. See
+ [`navigation`](#navigation). **Default:** `{}`.
+- `bundler` {WebBundler} Adapter that renders server entries and writes the
+ client and HTML output. See [Bundler adapters](#bundler-adapters).
+ **Default:** `createViteBundler()`.
### `head`
-The `head` object controls the project-specific markup injected into the
-document `` (rendered into the template's `${head}` placeholder). It has
-three keys:
+- `meta` {Array} `` tags. Each entry is an attribute bag, e.g.
+ `{ name: 'description', content: '…' }`.
+- `links` {Array} `` tags. Each entry is an attribute bag, e.g.
+ `{ rel: 'icon', href: '…' }`.
+- `html` {Array} Raw HTML strings appended verbatim — an escape hatch for
+ anything not expressible above.
-| Key | Type | Description |
-| ------- | ------- | ------------------------------------------------------------------------------------------- |
-| `meta` | `array` | `` tags. Each entry is an attribute bag, e.g. `{ name: 'description', content: '…' }` |
-| `links` | `array` | `` tags. Each entry is an attribute bag, e.g. `{ rel: 'icon', href: '…' }` |
-| `html` | `array` | Raw HTML strings appended verbatim — an escape hatch for anything not expressible above |
+The `head` object controls the project-specific markup injected into the
+document `` (rendered into the template's `${head}` placeholder).
Each attribute bag is rendered as a tag: a boolean `true` becomes a valueless
attribute (e.g. `crossorigin`), and `false`/`null`/`undefined` attributes are
@@ -74,21 +86,21 @@ export default {
### `navigation`
+- `sidebar` {Array} Sidebar groups, each `{ groupName, items }`. Defaults to one
+ `API Documentation` group holding every page.
+- `navbar` {Array} Navigation bar items, each `{ text, link, target? }`.
+ Defaults to none, which renders no items.
+
The `navigation` object supplies the site's two navigation surfaces. Both keys
are optional; omit either one to keep that component's default.
-| Key | Type | Description |
-| --------- | ------- | ---------------------------------------------------------------------------------------------------------- |
-| `sidebar` | `array` | Sidebar groups, each `{ groupName, items }`. Defaults to one `API Documentation` group holding every page. |
-| `navbar` | `array` | Navigation bar items, each `{ text, link, target? }`. Defaults to none, which renders no items. |
-
Sidebar items are `{ label, link }` and may nest through an `items` array of
their own. A `label` is plain text, except that backticked spans render as
-`` (``'`fs` Generator'``), matching how page headings are rendered. A
-`link` is a page path without its extension (`/fs`, `/generators/web`): it is
-resolved against the page being rendered, so it obeys `useAbsoluteURLs` and
-highlights while it is the current page. Links starting with `http://` or
-`https://` are used as authored.
+`` (``'`fs`'``), matching how page headings are rendered. A `link` is a
+page path without its extension (`/fs`, `/generators/web`): it is resolved
+against the page being rendered, so it obeys `useAbsoluteURLs` and highlights
+while it is the current page. Links starting with `http://` or `https://` are
+used as authored.
Navigation bar links are always used as authored, since they typically point
outside the generated site. Give them a `target` of `'_blank'` to open in a new
@@ -124,14 +136,15 @@ omitted rather than rendered empty.
### Bundler adapters
-The `bundler` option accepts a small Doc Kit adapter rather than configuration
-for a particular build system:
+- `getEntryId` {Function} Return the module identifier placed in the populated
+ HTML for an API name.
+- `render` {Function} Bundle and execute the server `entries`, returning a `Map`
+ of API name to rendered HTML.
+- `build` {Function} Bundle the client `entries`, process the populated `pages`,
+ and write the complete output.
-| Method | Responsibility |
-| ------------ | ----------------------------------------------------------------------------------------- |
-| `getEntryId` | Return the module identifier placed in the populated HTML for an API name |
-| `render` | Bundle and execute the server `entries`, returning a `Map` of API name to rendered HTML |
-| `build` | Bundle the client `entries`, process the populated `pages`, and write the complete output |
+The `bundler` option accepts a small Doc Kit adapter rather than configuration
+for a particular build system.
Both `render` and `build` receive `{ entries, virtualImports, config }`; `build`
also receives `pages`. Entry maps use `${api}.jsx` keys, rendered server results
@@ -229,14 +242,18 @@ runs on the main thread and does not serialize the bundler to a worker.
### Default `imports`
-| Alias | Default | Description |
-| ------------------- | -------------------------------------------- | --------------------------------------------------- |
-| `#theme/Logo` | `@node-core/ui-components/Common/NodejsLogo` | Logo rendered inside the navigation bar |
-| `#theme/Navigation` | Built-in `NavBar` component | Top navigation bar |
-| `#theme/Sidebar` | Built-in `SideBar` component | Sidebar with version selector and page links |
-| `#theme/Metabar` | Built-in `MetaBar` component | Metadata bar displayed alongside page content |
-| `#theme/Footer` | Built-in `NoOp` component (renders nothing) | Optional footer rendered at the bottom of each page |
-| `#theme/Layout` | Built-in `Layout` component | Outermost wrapper around the full page |
+- `#theme/Logo` {string} Logo rendered inside the navigation bar.
+ **Default:** `'@node-core/ui-components/Common/NodejsLogo'`.
+- `#theme/Navigation` {string} Top navigation bar. Defaults to the built-in
+ `NavBar` component.
+- `#theme/Sidebar` {string} Sidebar with version selector and page links.
+ Defaults to the built-in `SideBar` component.
+- `#theme/Metabar` {string} Metadata bar displayed alongside page content.
+ Defaults to the built-in `MetaBar` component.
+- `#theme/Footer` {string} Optional footer rendered at the bottom of each page.
+ Defaults to the built-in `NoOp` component, which renders nothing.
+- `#theme/Layout` {string} Outermost wrapper around the full page. Defaults to
+ the built-in `Layout` component.
Override any alias in your config file to swap in a custom component:
@@ -312,20 +329,25 @@ import { project, repository, editURL } from '#theme/config';
### Available exports
-| Export | Type | Description |
-| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `project` | `string` | Project name (e.g. `'Node.js'`) |
-| `repository` | `string` | GitHub repository in `owner/repo` format |
-| `version` | `string` | Current version label (e.g. `'v22.x'`) |
-| `versions` | `Array<{ url, label, major }>` | Pre-computed version entries with labels and URL templates (only `{path}` remains for per-page use) |
-| `editURL` | `string` | Partially populated "edit this page" URL template (only `{path}` remains) |
-| `pages` | `Array<[string, string]>` | Sorted `[name, path]` tuples for sidebar navigation |
-| `navigation` | `object` | Mirrors the configured `navigation` (consumed by the built-in `SideBar` and `NavBar`) |
-| `useAbsoluteURLs` | `boolean` | Whether internal links use absolute URLs (mirrors config value) |
-| `baseURL` | `string` | Base URL for the documentation site (used when `useAbsoluteURLs` is `true`) |
-| `languageDisplayNameMap` | `Map` | Shiki language alias → display name map for code blocks |
-| `remoteConfigUrl` | `string` | Mirrors the configured `remoteConfigUrl` (fetched client-side by `RemoteLoadableBanner` to load announcement banners) |
-| `server` | `boolean` | Whether the current bundle is the server build |
+- `project` {string} Project name (e.g. `'Node.js'`).
+- `repository` {string} GitHub repository in `owner/repo` format.
+- `version` {string} Current version label (e.g. `'v22.x'`).
+- `versions` {Array} Pre-computed version entries, each `{ url, label, major }`,
+ with labels and URL templates (only `{path}` remains for per-page use).
+- `editURL` {string} Partially populated "edit this page" URL template (only
+ `{path}` remains).
+- `pages` {Array} Sorted `[name, path]` tuples for sidebar navigation.
+- `navigation` {Object} Mirrors the configured `navigation` (consumed by the
+ built-in `SideBar` and `NavBar`).
+- `useAbsoluteURLs` {boolean} Whether internal links use absolute URLs (mirrors
+ config value).
+- `baseURL` {string} Base URL for the documentation site (used when
+ `useAbsoluteURLs` is `true`).
+- `languageDisplayNameMap` {Map} Shiki language alias → display
+ name map for code blocks.
+- `remoteConfigUrl` {string} Mirrors the configured `remoteConfigUrl` (fetched
+ client-side by `RemoteLoadableBanner` to load announcement banners).
+- `server` {boolean} Whether the current bundle is the server build.
### Usage in custom components
@@ -351,16 +373,14 @@ export default ({ metadata }) => (
## Layout props
-The `Layout` component receives the following props:
-
-| Prop | Type | Description |
-| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `metadata` | `object` | Serialized page metadata — all YAML frontmatter properties plus `addedIn`, `basename`, `path`, and any custom user-defined fields |
-| `headings` | `Array` | Pre-computed table of contents heading entries |
-| `readingTime` | `string` | Estimated reading time (e.g. `'5 min read'`) |
-| `children` | `ComponentChildren` | Processed page content |
+- `metadata` {Object} Serialized page metadata — all YAML frontmatter properties
+ plus `addedIn`, `basename`, `path`, and any custom user-defined fields.
+- `headings` {Array} Pre-computed table of contents heading entries.
+- `readingTime` {string} Estimated reading time (e.g. `'5 min read'`).
+- `children` {ComponentChildren} Processed page content.
-Custom Layout components can use any combination of these props alongside `#theme/config` imports.
+The `Layout` component receives the props above. Custom Layout components can use
+any combination of them alongside `#theme/config` imports.
## HTML template
@@ -368,17 +388,18 @@ The HTML template file (set via `templatePath`) uses JavaScript template literal
### Available template variables
-| Variable | Type | Description |
-| ------------------ | -------- | ----------------------------------------------------------------- |
-| `title` | `string` | Fully resolved page title (e.g. `'File system \| Node.js v22.x'`) |
-| `dehydrated` | `string` | Server-rendered HTML for the page content |
-| `entrypoint` | `string` | Adapter-provided module identifier for this page's hydration |
-| `speculationRules` | `string` | Speculation rules JSON for prefetching |
-| `themeScript` | `string` | Inline script that applies the saved theme before paint |
-| `root` | `string` | Relative or absolute path to the site root |
-| `metadata` | `object` | Full page metadata (frontmatter, path, heading, etc.) |
-| `config` | `object` | The resolved web generator configuration |
-| `head` | `string` | Pre-rendered ``/``/raw markup from the `head` config |
+- `title` {string} Fully resolved page title (e.g.
+ `'File system | Node.js v22.x'`).
+- `dehydrated` {string} Server-rendered HTML for the page content.
+- `entrypoint` {string} Adapter-provided module identifier for this page's
+ hydration.
+- `speculationRules` {string} Speculation rules JSON for prefetching.
+- `themeScript` {string} Inline script that applies the saved theme before paint.
+- `root` {string} Relative or absolute path to the site root.
+- `metadata` {Object} Full page metadata (frontmatter, path, heading, etc.).
+- `config` {Object} The resolved web generator configuration.
+- `head` {string} Pre-rendered ``/``/raw markup from the `head`
+ config.
Since the template supports arbitrary JS expressions, you can use conditionals and method calls:
diff --git a/www/doc-kit.config.mjs b/www/doc-kit.config.mjs
index e9d0ba9e..017c440a 100644
--- a/www/doc-kit.config.mjs
+++ b/www/doc-kit.config.mjs
@@ -15,7 +15,7 @@ const generatorItems = globSync('packages/core/src/generators/*/README.md', {
.map(file => basename(dirname(file)))
.sort()
.map(name => ({
- label: `\`${name}\` Generator`,
+ label: `\`${name}\``,
link: `/generators/${name}`,
}));
@@ -28,7 +28,7 @@ const DESCRIPTION =
/** @type {import('../packages/core/src/utils/configuration/types').Configuration} */
export default {
- target: ['orama-db', 'web'],
+ target: ['orama-db', 'legacy-json', 'web'],
global: {
// `www/content/` is assembled by `scripts/build-docs-content.mjs`.
@@ -69,6 +69,8 @@ export default {
// each slug back to its true origin.
editURL: `https://github.com/${REPOSITORY}`,
+ pathsToCopy: [{ [join(ROOT, 'content')]: '.' }],
+
navigation: {
sidebar: [
{