refactor(react): extract @nodejs/doc-kit-generator-react package

.c8rc.json

@@ -4,7 +4,7 @@
     "eslint.config.mjs",
     "**/fixtures",
     "packages/core/src/generators/legacy-html/assets",
-    "packages/core/src/generators/web/ui",
+    "packages/react/src/html/ui",
     "**/*.d.ts"
   ]
 }

.changeset/react-kitten-package.md

@@ -0,0 +1,12 @@
+---
+'@nodejs/doc-kit-generator-react': minor
+'@node-core/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 `@node-core/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`.

.prettierignore

@@ -5,7 +5,7 @@ packages/core/src/generators/api-links/__tests__/fixtures/
 *.snapshot
 
 # Templates
-packages/core/src/generators/web/template.html
+packages/react/src/html/template.html
 
 # Output
 out/

README.md

@@ -111,11 +111,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 \

beta/doc-kit.config.mjs

@@ -1,5 +1,5 @@
 export default {
-  web: {
+  html: {
     remoteConfigUrl:
       'https://raw.githubusercontent.com/nodejs/doc-kit/main/beta/site.json',
 

docs/comparators.md

@@ -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
 

docs/generators.md

@@ -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.
@@ -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,
 };

eslint.config.mjs

@@ -96,7 +96,7 @@ export default defineConfig([
   {
     files: [
       'packages/core/src/generators/legacy-html/assets/*.js',
-      'packages/core/src/generators/web/ui/**/*',
+      'packages/react/src/html/ui/**/*',
     ],
     languageOptions: {
       globals: {

packages/core/package.json

@@ -23,17 +23,12 @@
     "./ast": "./src/generators/ast/index.mjs",
     "./ast-js": "./src/generators/ast-js/index.mjs",
     "./json-simple": "./src/generators/json-simple/index.mjs",
-    "./jsx-ast": "./src/generators/jsx-ast/index.mjs",
     "./legacy-html": "./src/generators/legacy-html/index.mjs",
     "./legacy-html-all": "./src/generators/legacy-html-all/index.mjs",
     "./legacy-json": "./src/generators/legacy-json/index.mjs",
     "./legacy-json-all": "./src/generators/legacy-json-all/index.mjs",
-    "./llms-txt": "./src/generators/llms-txt/index.mjs",
     "./man-page": "./src/generators/man-page/index.mjs",
     "./metadata": "./src/generators/metadata/index.mjs",
-    "./orama-db": "./src/generators/orama-db/index.mjs",
-    "./sitemap": "./src/generators/sitemap/index.mjs",
-    "./web": "./src/generators/web/index.mjs",
     "./package.json": "./package.json",
     "./shiki.config.mjs": "./shiki.config.mjs",
     "./src/*": "./src/*",
@@ -53,35 +48,19 @@
     "README.md"
   ],
   "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",
@@ -98,7 +77,14 @@
     "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"
+  },
+  "peerDependencies": {
+    "@nodejs/doc-kit-generator-react": "^0.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nodejs/doc-kit-generator-react": {
+      "optional": true
+    }
   }
 }

packages/core/src/generators/__tests__/index.test.mjs

@@ -1,13 +1,25 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-import { allGenerators, publicGenerators } from '../index.mjs';
+import {
+  allGenerators,
+  deprecatedGenerators,
+  publicGenerators,
+} from '../index.mjs';
 import { loadGenerator, resolveGeneratorSpecifier } from '../loader.mjs';
 
 const validDependencies = Object.values(allGenerators);
 
+// Deprecated aliases intentionally have keys that differ from the
+// generator's name, so they are excluded from the name-match assertions.
+const currentGenerators = Object.fromEntries(
+  Object.entries(allGenerators).filter(
+    ([name]) => !(name in deprecatedGenerators)
+  )
+);
+
 const loadedGenerators = await Promise.all(
-  Object.entries(allGenerators).map(async ([name, specifier]) => [
+  Object.entries(currentGenerators).map(async ([name, specifier]) => [
     name,
     specifier,
     await loadGenerator(specifier),
@@ -50,6 +62,15 @@ describe('All Generators', () => {
     });
   });
 
+  it('should resolve deprecated aliases to loadable generators', async () => {
+    for (const [name, specifier] of Object.entries(deprecatedGenerators)) {
+      assert.equal(resolveGeneratorSpecifier(name), specifier);
+
+      const generator = await loadGenerator(specifier);
+      assert.ok(generator.name, `Deprecated alias "${name}" must load`);
+    }
+  });
+
   it('should have ast generator as a top-level generator with no dependencies', async () => {
     const ast = await loadGenerator(allGenerators.ast);
     assert.ok(ast, 'ast generator should exist');

packages/core/src/generators/index.mjs

@@ -2,7 +2,7 @@
 
 /**
  * Maps the shorthand names accepted by the CLI and configuration files
- * (e.g. `--target web`) to the import specifiers they resolve to.
+ * (e.g. `--target html`) to the import specifiers they resolve to.
  *
  * Generators are loaded dynamically by specifier (see `./loader.mjs`), so this
  * module must not import any generator code — it is purely a lookup table.
@@ -18,10 +18,10 @@ export const publicGenerators = {
   'legacy-json-all': '@node-core/doc-kit/legacy-json-all',
   'addon-verify': '@node-core/doc-kit/addon-verify',
   'api-links': '@node-core/doc-kit/api-links',
-  'orama-db': '@node-core/doc-kit/orama-db',
-  'llms-txt': '@node-core/doc-kit/llms-txt',
-  sitemap: '@node-core/doc-kit/sitemap',
-  web: '@node-core/doc-kit/web',
+  'orama-db': '@nodejs/doc-kit-generator-react/orama-db',
+  'llms-txt': '@nodejs/doc-kit-generator-react/llms-txt',
+  sitemap: '@nodejs/doc-kit-generator-react/sitemap',
+  html: '@nodejs/doc-kit-generator-react/html',
 };
 
 // These ones are special since they don't produce standard output,
@@ -30,11 +30,19 @@ export const publicGenerators = {
 const internalGenerators = {
   ast: '@node-core/doc-kit/ast',
   metadata: '@node-core/doc-kit/metadata',
-  'jsx-ast': '@node-core/doc-kit/jsx-ast',
+  'jsx-ast': '@nodejs/doc-kit-generator-react/jsx-ast',
   'ast-js': '@node-core/doc-kit/ast-js',
 };
 
+// Former names kept resolvable for existing invocations and config files.
+// Unlike the maps above, keys here intentionally differ from the generator's
+// `name` property.
+export const deprecatedGenerators = {
+  web: '@nodejs/doc-kit-generator-react/html',
+};
+
 export const allGenerators = {
   ...publicGenerators,
   ...internalGenerators,
+  ...deprecatedGenerators,
 };