feat(docs): add documentation for doc-kit

.changeset/fix-relative-parent-path.md

@@ -0,0 +1,9 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Fix `relative()` URL resolution when the target path is a prefix of the current
+page's path (e.g. `/generators` from `/generators/web`): the target's final
+segment was consumed as a common directory, producing `.` instead of
+`../generators`. Unreachable in flat page layouts; surfaced by sites with
+nested input directories.

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Documentation Site
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build docs site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
+        with:
+          egress-policy: audit
+
+      - name: Git Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: node --run docs:build
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs-site
+          path: www/out

.gitignore

@@ -6,6 +6,9 @@ npm-debug.log
 out
 base
 
+# Docs site content, assembled by scripts/build-docs-content.mjs
+www/content
+
 # Tests
 coverage
 junit.xml

.prettierignore

@@ -10,6 +10,9 @@ src/generators/web/template.html
 # Output
 out/
 
+# Docs-site content, assembled by scripts/build-docs-content.mjs
+www/content/
+
 # Generated Files
 src/generators/metadata/maps/mdn.json
 

.prettierrc.json

@@ -7,5 +7,13 @@
   "trailingComma": "es5",
   "bracketSpacing": true,
   "bracketSameLine": false,
-  "arrowParens": "avoid"
+  "arrowParens": "avoid",
+  "overrides": [
+    {
+      "files": "www/pages/**/*.md",
+      "options": {
+        "proseWrap": "always"
+      }
+    }
+  ]
 }

docs/configuration.md

@@ -16,6 +16,8 @@ Configuration files can be either:
 
 ```javascript
 export default {
+  // targets, alternatively supplied by command line flags
+  target: ['orama-db', 'web'],
   global: {
     version: '20.0.0',
     minify: true,

package.json

@@ -21,6 +21,7 @@
     "prepare": "husky || exit 0",
     "run": "node bin/cli.mjs",
     "watch": "node --watch bin/cli.mjs",
+    "docs:build": "bash scripts/vercel-docs-build.sh",
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "release": "changeset publish"
@@ -29,6 +30,16 @@
   "bin": {
     "doc-kit": "./bin/cli.mjs"
   },
+  "files": [
+    "src",
+    "!src/**/*.test.mjs",
+    "!src/**/__tests__",
+    "bin",
+    "shiki.config.mjs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",

scripts/build-docs-content.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+// Assembles `www/content/` — the input tree for the doc-kit documentation
+// site — from three sources that live elsewhere in the repo:
+//
+//   www/pages/*.md              authored narrative pages, copied verbatim
+//   docs/*.md                   the existing reference docs
+//   src/generators/*/README.md  per-generator config reference, written to
+//                               `generators/<name>.md`
+//
+// `www/content/` is a build artifact and is gitignored. Run this before
+// invoking the `web` generator against it.
+
+import { glob, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+const ROOT = join(import.meta.dirname, '..');
+const CONTENT = join(ROOT, 'www', 'content');
+
+const SOURCES = [
+  { pattern: 'www/pages/*.md', rename: basename },
+  { pattern: 'docs/*.md', rename: basename },
+  {
+    pattern: 'src/generators/*/README.md',
+    rename: file => `generators/${basename(dirname(file))}.md`,
+  },
+];
+
+/**
+ * Collects the `{ name, markdown }` pages to write into `www/content/`.
+ *
+ * @returns {Promise<Array<{ name: string, markdown: string }>>}
+ */
+const collectPages = async () => {
+  const groups = await Promise.all(
+    SOURCES.map(async ({ pattern, rename }) => {
+      const files = await Array.fromAsync(glob(pattern, { cwd: ROOT }));
+
+      return Promise.all(
+        files.sort().map(async file => ({
+          name: rename(file),
+          markdown: await readFile(join(ROOT, file), 'utf-8'),
+        }))
+      );
+    })
+  );
+
+  return groups.flat();
+};
+
+const pages = await collectPages();
+
+await rm(CONTENT, { recursive: true, force: true });
+
+await Promise.all(
+  [...new Set(pages.map(({ name }) => dirname(join(CONTENT, name))))].map(dir =>
+    mkdir(dir, { recursive: true })
+  )
+);
+
+await Promise.all(
+  pages.map(({ name, markdown }) => writeFile(join(CONTENT, name), markdown))
+);
+
+console.log(`Wrote ${pages.length} pages to www/content/`);

scripts/vercel-docs-build.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# Build the doc-kit documentation site into `www/out/`.
+
+node scripts/build-docs-content.mjs
+
+node bin/cli.mjs generate \
+  --config-file ./www/doc-kit.config.mjs \
+  --log-level debug

src/generators/addon-verify/README.md

@@ -1,8 +1,8 @@
-## `addon-verify` Generator
+# `addon-verify` Generator
 
 The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and generates a file list to facilitate C++ compilation and JavaScript runtime validations for Node.js addon examples.
 
-### Configuring
+## Configuring
 
 The `addon-verify` generator accepts the following configuration options:
 

src/generators/api-links/README.md

@@ -1,8 +1,8 @@
-## `api-links` Generator
+# `api-links` Generator
 
 The `api-links` generator creates a mapping of publicly accessible functions to their source locations in the Node.js repository by analyzing JavaScript source files.
 
-### Configuring
+## Configuring
 
 The `api-links` generator accepts the following configuration options:
 

src/generators/ast-js/README.md

@@ -1,8 +1,8 @@
-## `ast-js` Generator
+# `ast-js` Generator
 
 The `ast-js` generator parses JavaScript source files into AST (Abstract Syntax Tree) representations using the Acorn parser.
 
-### Configuring
+## Configuring
 
 The `ast-js` generator accepts the following configuration options:
 

src/generators/ast/README.md

@@ -1,8 +1,8 @@
-## `ast` Generator
+# `ast` Generator
 
 The `ast` generator parses Markdown API documentation files into AST (Abstract Syntax Tree) representations, parallelizing the parsing across worker threads for better performance.
 
-### Configuring
+## Configuring
 
 The `ast` generator accepts the following configuration options:
 

src/generators/json-simple/README.md

@@ -1,8 +1,8 @@
-## `json-simple` Generator
+# `json-simple` Generator
 
 The `json-simple` generator creates a simplified JSON version of the API documentation, primarily for debugging and testing purposes.
 
-### Configuring
+## Configuring
 
 The `json-simple` generator accepts the following configuration options:
 

src/generators/jsx-ast/README.md

@@ -1,8 +1,8 @@
-## `jsx-ast` Generator
+# `jsx-ast` Generator
 
 The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AST, transforming API documentation metadata into React-compatible JSX representations.
 
-### Configuring
+## Configuring
 
 The `jsx-ast` generator accepts the following configuration options:
 

src/generators/legacy-html-all/README.md

@@ -1,8 +1,8 @@
-## `legacy-html-all` Generator
+# `legacy-html-all` Generator
 
 The `legacy-html-all` generator creates a single `all.html` file containing all API documentation modules in one file, based on the output from the `legacy-html` generator.
 
-### Configuring
+## Configuring
 
 The `legacy-html-all` generator accepts the following configuration options:
 

src/generators/legacy-html/README.md

@@ -1,8 +1,8 @@
-## `legacy-html` Generator
+# `legacy-html` Generator
 
 The `legacy-html` generator creates legacy HTML documentation pages for Node.js API documentation with included assets and styles for retro-compatibility.
 
-### Configuring
+## Configuring
 
 The `legacy-html` generator accepts the following configuration options:
 

src/generators/legacy-json-all/README.md

@@ -1,8 +1,8 @@
-## `legacy-json-all` Generator
+# `legacy-json-all` Generator
 
 The `legacy-json-all` generator consolidates data from the `legacy-json` generator into a single `all.json` file containing all API modules.
 
-### Configuring
+## Configuring
 
 The `legacy-json-all` generator accepts the following configuration options:
 

src/generators/legacy-json/README.md

@@ -1,8 +1,8 @@
-## `legacy-json` Generator
+# `legacy-json` Generator
 
 The `legacy-json` generator creates legacy JSON files for the API documentation for retro-compatibility with the previous documentation format.
 
-### Configuring
+## Configuring
 
 The `legacy-json` generator accepts the following configuration options:
 

src/generators/llms-txt/README.md

@@ -1,8 +1,8 @@
-## `llms-txt` Generator
+# `llms-txt` Generator
 
 The `llms-txt` generator creates a `llms.txt` file to provide information to Large Language Models (LLMs) at inference time, containing links to all API documentation.
 
-### Configuring
+## Configuring
 
 The `llms-txt` generator accepts the following configuration options:
 

src/generators/man-page/README.md

@@ -1,8 +1,8 @@
-## `man-page` Generator
+# `man-page` Generator
 
 The `man-page` generator creates a Unix man page version of the Node.js CLI documentation in mdoc format.
 
-### Configuring
+## Configuring
 
 The `man-page` generator accepts the following configuration options:
 

src/generators/metadata/README.md

@@ -1,8 +1,8 @@
-## `metadata` Generator
+# `metadata` Generator
 
 The `metadata` generator creates a flattened list of metadata entries from API documentation, extracting structured information about functions, classes, methods, and other API elements.
 
-### Configuring
+## Configuring
 
 The `metadata` generator accepts the following configuration options:
 

src/generators/orama-db/README.md

@@ -1,8 +1,8 @@
-## `orama-db` Generator
+# `orama-db` Generator
 
 The `orama-db` generator creates an Orama database for the API documentation to enable full-text search functionality.
 
-### Configuring
+## Configuring
 
 The `orama-db` generator accepts the following configuration options:
 

src/generators/sitemap/README.md

@@ -1,8 +1,8 @@
-## `sitemap` Generator
+# `sitemap` Generator
 
 The `sitemap` generator creates a `sitemap.xml` file for search engine optimization (SEO), listing all API documentation pages.
 
-### Configuring
+## Configuring
 
 The `sitemap` generator accepts the following configuration options: