diff --git a/.c8rc.json b/.c8rc.json
index 4ce81ec8..fbc2a9e6 100644
--- a/.c8rc.json
+++ b/.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"
]
}
diff --git a/.changeset/react-kitten-package.md b/.changeset/react-kitten-package.md
new file mode 100644
index 00000000..cf250c1c
--- /dev/null
+++ b/.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`.
diff --git a/.prettierignore b/.prettierignore
index 86080826..6e8a14b1 100644
--- a/.prettierignore
+++ b/.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/
diff --git a/README.md b/README.md
index 1bcadb89..967e4878 100644
--- a/README.md
+++ b/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 \
diff --git a/beta/doc-kit.config.mjs b/beta/doc-kit.config.mjs
index 07484c9c..5edaaa29 100644
--- a/beta/doc-kit.config.mjs
+++ b/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',
diff --git a/docs/comparators.md b/docs/comparators.md
index 6f87f379..0046c78a 100644
--- a/docs/comparators.md
+++ b/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
diff --git a/docs/generators.md b/docs/generators.md
index 33f02c02..a2048499 100644
--- a/docs/generators.md
+++ b/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,
};
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 197acf57..9e92946a 100644
--- a/eslint.config.mjs
+++ b/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: {
diff --git a/package-lock.json b/package-lock.json
index 3a8ce0c9..541a633b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1387,6 +1387,10 @@
"node": ">=20"
}
},
+ "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",
@@ -11205,35 +11209,19 @@
"name": "@node-core/doc-kit",
"version": "1.4.3",
"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 +11238,51 @@
"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": {
+ "@nodejs/doc-kit-generator-react": "^0.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@nodejs/doc-kit-generator-react": {
+ "optional": true
+ }
+ }
+ },
+ "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/doc-kit": "^1.4.3",
+ "@node-core/rehype-shiki": "^1.4.3",
+ "@node-core/ui-components": "^1.7.4",
+ "@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/packages/core/package.json b/packages/core/package.json
index dec60f50..96ffaf80 100644
--- a/packages/core/package.json
+++ b/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
+ }
}
}
diff --git a/packages/core/src/generators/__tests__/index.test.mjs b/packages/core/src/generators/__tests__/index.test.mjs
index cd3bfdcf..e0af8670 100644
--- a/packages/core/src/generators/__tests__/index.test.mjs
+++ b/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');
diff --git a/packages/core/src/generators/index.mjs b/packages/core/src/generators/index.mjs
index a8b1a68f..f356169f 100644
--- a/packages/core/src/generators/index.mjs
+++ b/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,
};
diff --git a/packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs b/packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs
deleted file mode 100644
index fb74faa4..00000000
--- a/packages/core/src/generators/sitemap/utils/createPageSitemapEntry.mjs
+++ /dev/null
@@ -1,18 +0,0 @@
-import { populate } from '../../../utils/configuration/templates.mjs';
-
-/**
- * Builds an API doc sitemap url.
- *
- * @param {import('../../metadata/types').MetadataEntry} entry
- * @param {import('../../../utils/configuration/types').Configuration['sitemap']} config
- * @returns {import('../types').SitemapEntry}
- */
-export const createPageSitemapEntry = (entry, config, lastmod) => ({
- loc: populate(config.pageURL, {
- ...config,
- path: entry.path,
- }),
- lastmod,
- changefreq: 'weekly',
- priority: '0.8',
-});
diff --git a/packages/core/src/generators/web/template.html b/packages/core/src/generators/web/template.html
deleted file mode 100644
index e3792678..00000000
--- a/packages/core/src/generators/web/template.html
+++ /dev/null
@@ -1,22 +0,0 @@
-
-
-
-
-
-
- ${title}
-
-
-
- ${head}
-
-
-
-
-
-
-
- ${dehydrated}
-
-
-
diff --git a/packages/core/src/utils/remark.mjs b/packages/core/src/utils/remark.mjs
index 1aacd37a..3935b7ea 100644
--- a/packages/core/src/utils/remark.mjs
+++ b/packages/core/src/utils/remark.mjs
@@ -1,10 +1,5 @@
'use strict';
-import rehypeShikiji from '@node-core/rehype-shiki/plugin';
-import recmaJsx from 'recma-jsx';
-import recmaStringify from 'recma-stringify';
-import rehypeRaw from 'rehype-raw';
-import rehypeRecma from 'rehype-recma';
import rehypeStringify from 'rehype-stringify';
import remarkGfm from 'remark-gfm';
import remarkMdx from 'remark-mdx';
@@ -12,49 +7,24 @@ import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import remarkStringify from 'remark-stringify';
import { unified } from 'unified';
-import { visit } from 'unist-util-visit';
-import syntaxHighlighter, { highlighter } from './highlighter.mjs';
+import syntaxHighlighter from './highlighter.mjs';
import { lazy } from './misc.mjs';
-import {
- typeAnnotationToHast,
- typeAnnotationToHighlightedHast,
-} from './type-annotations/hast.mjs';
+import { typeAnnotationToHast } from './type-annotations/hast.mjs';
import remarkTypeAnnotations from './type-annotations/remark.mjs';
-import { AST_NODE_TYPES } from '../generators/jsx-ast/constants.mjs';
-import transformAlerts from '../generators/jsx-ast/utils/plugins/alerts.mjs';
-import transformElements from '../generators/jsx-ast/utils/plugins/transformer.mjs';
-const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)];
-const codeMetaProperty = 'codeMeta';
-
-/**
- * Stores fenced code metadata on properties before rehypeRaw reparses the tree.
- */
-const preserveCodeMeta = () => tree => {
- visit(tree, 'element', node => {
- const meta = node.data?.meta;
-
- if (node.tagName === 'code' && typeof meta === 'string') {
- node.properties ||= {};
- node.properties[codeMetaProperty] = meta;
- }
- });
-};
-
-/**
- * Restores fenced code metadata so the Shiki plugin can read displayName.
- */
-const restoreCodeMeta = () => tree => {
- visit(tree, 'element', node => {
- const meta = node.properties?.[codeMetaProperty];
-
- if (node.tagName === 'code' && typeof meta === 'string') {
- node.data = { ...node.data, meta };
- delete node.properties[codeMetaProperty];
- }
- });
-};
+// MDX node types that may appear in trees parsed by `getRemarkMdx`; the
+// rehype pipelines pass them through untouched.
+const passThrough = [
+ 'element',
+ 'mdxJsxTextElement',
+ 'mdxJsxFlowElement',
+ 'mdxJsxAttribute',
+ 'mdxJsxAttributeValueExpression',
+ 'mdxFlowExpression',
+ 'mdxTextExpression',
+ 'mdxjsEsm',
+];
/**
* Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown)
@@ -125,34 +95,3 @@ export const getRemarkRehypeWithShiki = lazy(() =>
// and we trust the sources of the Markdown files
.use(rehypeStringify, { allowDangerousHtml: true })
);
-
-const singletonShiki = await rehypeShikiji({ highlighter });
-
-/**
- * Retrieves an instance of Remark configured to output JSX code.
- * including parsing Code Boxes with syntax highlighting
- */
-export const getRemarkRecma = lazy(() =>
- unified()
- .use(remarkParse)
- .use(transformAlerts)
- // We make Rehype ignore existing HTML nodes, and JSX nodes
- // as these are nodes we manually created during the generation process
- // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
- // and we trust the sources of the Markdown files
- .use(remarkRehype, {
- allowDangerousHtml: true,
- passThrough,
- // The web pipeline gets Shiki-highlighted types with embedded links
- handlers: { typeAnnotation: typeAnnotationToHighlightedHast },
- })
- .use(preserveCodeMeta)
- // Any `raw` HTML in the markdown must be converted to AST in order for Recma to understand it
- .use(rehypeRaw, { passThrough })
- .use(restoreCodeMeta)
- .use(() => singletonShiki)
- .use(transformElements)
- .use(rehypeRecma)
- .use(recmaJsx)
- .use(recmaStringify)
-);
diff --git a/packages/react/package.json b/packages/react/package.json
new file mode 100644
index 00000000..636b9c9e
--- /dev/null
+++ b/packages/react/package.json
@@ -0,0 +1,57 @@
+{
+ "name": "@nodejs/doc-kit-generator-react",
+ "type": "module",
+ "version": "0.0.0",
+ "description": "React/JSX-based generators for @node-core/doc-kit: html, jsx-ast, llms-txt, sitemap, and orama-db",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nodejs/doc-kit.git",
+ "directory": "packages/react"
+ },
+ "exports": {
+ "./html": "./src/html/index.mjs",
+ "./html/bundlers/vite": "./src/html/bundlers/vite.mjs",
+ "./jsx-ast": "./src/jsx-ast/index.mjs",
+ "./llms-txt": "./src/llms-txt/index.mjs",
+ "./orama-db": "./src/orama-db/index.mjs",
+ "./sitemap": "./src/sitemap/index.mjs",
+ "./package.json": "./package.json"
+ },
+ "files": [
+ "src",
+ "!src/**/*.test.mjs",
+ "!src/**/__tests__",
+ "CHANGELOG.md",
+ "LICENSE",
+ "README.md"
+ ],
+ "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/doc-kit": "^1.4.3",
+ "@node-core/rehype-shiki": "^1.4.3",
+ "@node-core/ui-components": "^1.7.4",
+ "@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/packages/core/src/generators/web/README.md b/packages/react/src/html/README.md
similarity index 95%
rename from packages/core/src/generators/web/README.md
rename to packages/react/src/html/README.md
index c86c521b..7f875f7a 100644
--- a/packages/core/src/generators/web/README.md
+++ b/packages/react/src/html/README.md
@@ -1,6 +1,6 @@
-# `web` Generator
+# `html` Generator
-The `web` generator transforms JSX AST entries into complete web bundles. Its
+The `html` generator transforms JSX AST entries into complete web bundles. Its
bundler adapter builds server-rendered HTML and client-side JavaScript, CSS, and
imported assets, then writes the complete static site to `output`. Vite is the
default adapter, but projects can supply an adapter for webpack or another
@@ -64,7 +64,7 @@ for any project:
```js
// doc-kit.config.mjs
export default {
- web: {
+ html: {
head: {
meta: [
{ name: 'description', content: 'My project documentation' },
@@ -97,7 +97,7 @@ are optional; omit either one to keep that component's default.
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`'``), matching how page headings are rendered. A `link` is a
-page path without its extension (`/fs`, `/generators/web`): it is resolved
+page path without its extension (`/fs`, `/generators/html`): 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.
@@ -109,7 +109,7 @@ tab and mark them with an external-link icon.
```js
// doc-kit.config.mjs
export default {
- web: {
+ html: {
navigation: {
sidebar: [
{
@@ -149,7 +149,7 @@ 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
use `api` keys, and page maps use output-relative HTML file names. `config` is
-the resolved web configuration.
+the resolved `html` configuration.
The adapter must compile the generated Preact JSX and CSS imports and resolve
the supplied theme aliases and virtual modules. The generated `#theme/config`
@@ -181,7 +181,7 @@ export const createWebpackBundler = webpackOptions => ({
import { createWebpackBundler } from './webpack-bundler.mjs';
export default {
- web: {
+ html: {
bundler: createWebpackBundler({
// Project-owned webpack configuration.
}),
@@ -197,11 +197,11 @@ directly and pass Vite's `UserConfig` to it:
```js
// doc-kit.config.mjs
-import { createViteBundler } from '@node-core/doc-kit/src/generators/web/bundlers/vite.mjs';
+import { createViteBundler } from '@nodejs/doc-kit-generator-react/html/bundlers/vite';
import myVitePlugin from './my-vite-plugin.mjs';
export default {
- web: {
+ html: {
bundler: createViteBundler({
plugins: [myVitePlugin()],
define: {
@@ -237,7 +237,7 @@ name to `createViteBundler` when another tool needs one. The generated HTML
already references the correct hashed scripts, stylesheets, imported assets,
and module preloads.
-Function-valued plugins and hooks are supported because the `web` generator
+Function-valued plugins and hooks are supported because the `html` generator
runs on the main thread and does not serialize the bundler to a worker.
### Default `imports`
@@ -260,7 +260,7 @@ Override any alias in your config file to swap in a custom component:
```js
// doc-kit.config.mjs
export default {
- web: {
+ html: {
imports: {
'#theme/Logo': './src/MyLogo.jsx',
'#theme/Sidebar': './src/MySidebar.jsx',
@@ -282,7 +282,7 @@ real module path:
```js
// doc-kit.config.mjs
export default {
- web: {
+ html: {
components: {
// Shorthand — equivalent to { name: 'Hero', source: '#theme/Hero' }
Hero: '#theme/Hero',
@@ -321,7 +321,7 @@ There are {stats.length} APIs documented.
## `#theme/config` virtual module
-The `web` generator provides a `#theme/config` virtual module that exposes pre-computed configuration as named exports. Any component (including custom overrides) can import the values it needs, and tree-shaking removes the rest.
+The `html` generator provides a `#theme/config` virtual module that exposes pre-computed configuration as named exports. Any component (including custom overrides) can import the values it needs, and tree-shaking removes the rest.
```js
import { project, repository, editURL } from '#theme/config';
@@ -397,7 +397,7 @@ The HTML template file (set via `templatePath`) uses JavaScript template literal
- `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.
+- `config` {Object} The resolved `html` generator configuration.
- `head` {string} Pre-rendered ``/``/raw markup from the `head`
config.
diff --git a/packages/core/src/generators/web/__tests__/generate.test.mjs b/packages/react/src/html/__tests__/generate.test.mjs
similarity index 93%
rename from packages/core/src/generators/web/__tests__/generate.test.mjs
rename to packages/react/src/html/__tests__/generate.test.mjs
index bb052f99..0445a621 100644
--- a/packages/core/src/generators/web/__tests__/generate.test.mjs
+++ b/packages/react/src/html/__tests__/generate.test.mjs
@@ -4,9 +4,9 @@ import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { describe, it } from 'node:test';
+import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs';
import { jsx, toJs } from 'estree-util-to-js';
-import { setConfig } from '../../../utils/configuration/index.mjs';
import buildContent from '../../jsx-ast/utils/buildContent.mjs';
import { buildNotFoundPage } from '../../jsx-ast/utils/synthetic/404.mjs';
import { createViteBundler } from '../bundlers/vite.mjs';
@@ -53,12 +53,12 @@ const createTestConfiguration = async context => {
context.after(() => rm(output, { recursive: true, force: true }));
const config = await setConfig({
- target: ['web'],
+ target: ['html'],
output,
version: 'v22.0.0',
changelog: [],
generators: {
- web: {},
+ html: {},
},
});
@@ -93,7 +93,7 @@ describe('web generate', () => {
it('renders the configurable head without hardcoded defaults', async context => {
const { config, output } = await createTestConfiguration(context);
- config.web.head = {
+ config.html.head = {
meta: [
{ name: 'description', content: 'Custom project docs' },
{ property: 'og:image', content: 'https://example.com/og.png' },
@@ -116,8 +116,8 @@ describe('web generate', () => {
it('uses Vite base URLs for absolute client assets', async context => {
const { config, output } = await createTestConfiguration(context);
- config.web.useAbsoluteURLs = true;
- config.web.baseURL = 'https://example.com/docs';
+ config.html.useAbsoluteURLs = true;
+ config.html.baseURL = 'https://example.com/docs';
const notFoundPage = buildNotFoundPage();
const content = await buildContent(notFoundPage.entries, notFoundPage.head);
@@ -130,7 +130,7 @@ describe('web generate', () => {
it('applies configured Vite plugins', async context => {
const { config, output } = await createTestConfiguration(context);
- config.web.bundler = createViteBundler({
+ config.html.bundler = createViteBundler({
plugins: [
{
name: 'test-html-transform',
@@ -158,7 +158,7 @@ describe('web generate', () => {
const { config, output } = await createTestConfiguration(context);
const calls = [];
- config.web.bundler = {
+ config.html.bundler = {
getEntryId(api) {
calls.push(`entry:${api}`);
return `/custom/${api}.js`;
@@ -166,7 +166,7 @@ describe('web generate', () => {
async render({ entries, virtualImports, config: receivedConfig }) {
calls.push('server');
- assert.strictEqual(receivedConfig, config.web);
+ assert.strictEqual(receivedConfig, config.html);
assert.ok(entries.has('fs.jsx'));
assert.match(virtualImports['#theme/config'], /export const pages/);
assert.match(
@@ -181,7 +181,7 @@ describe('web generate', () => {
async build({ entries, virtualImports, pages, config: receivedConfig }) {
calls.push('client');
- assert.strictEqual(receivedConfig, config.web);
+ assert.strictEqual(receivedConfig, config.html);
assert.ok(entries.has('fs.jsx'));
assert.match(
virtualImports['#theme/config'],
diff --git a/packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs b/packages/react/src/html/bundlers/__tests__/vite.test.mjs
similarity index 94%
rename from packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs
rename to packages/react/src/html/bundlers/__tests__/vite.test.mjs
index 7ff724c6..0d8486ed 100644
--- a/packages/core/src/generators/web/bundlers/__tests__/vite.test.mjs
+++ b/packages/react/src/html/bundlers/__tests__/vite.test.mjs
@@ -7,7 +7,8 @@ import { describe, it } from 'node:test';
import {
default as getConfig,
setConfig,
-} from '../../../../utils/configuration/index.mjs';
+} from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import {
createVirtualModulesPlugin,
createViteConfig,
@@ -17,12 +18,12 @@ import {
const output = join(tmpdir(), 'doc-kit-vite-test-output');
await setConfig({
- target: ['web'],
+ target: ['html'],
output,
version: 'v22.0.0',
changelog: [],
generators: {
- web: {},
+ html: {},
},
});
@@ -66,7 +67,7 @@ describe('Vite configuration', () => {
sources: new Map(),
input,
server: false,
- config: getConfig('web'),
+ config: getConfig('html'),
vite,
});
@@ -97,7 +98,7 @@ describe('Vite configuration', () => {
input,
server: true,
serverOutDir: serverOutput,
- config: getConfig('web'),
+ config: getConfig('html'),
vite,
});
@@ -125,7 +126,7 @@ describe('Vite SSR temporary output', () => {
],
]),
virtualImports: {},
- config: getConfig('web'),
+ config: getConfig('html'),
vite: {},
createTemporaryDirectory: async () => temporaryDirectory,
}),
diff --git a/packages/core/src/generators/web/bundlers/index.mjs b/packages/react/src/html/bundlers/index.mjs
similarity index 100%
rename from packages/core/src/generators/web/bundlers/index.mjs
rename to packages/react/src/html/bundlers/index.mjs
diff --git a/packages/core/src/generators/web/bundlers/vite.mjs b/packages/react/src/html/bundlers/vite.mjs
similarity index 99%
rename from packages/core/src/generators/web/bundlers/vite.mjs
rename to packages/react/src/html/bundlers/vite.mjs
index f6edcf23..5c9c3a82 100644
--- a/packages/core/src/generators/web/bundlers/vite.mjs
+++ b/packages/react/src/html/bundlers/vite.mjs
@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os';
import { basename, isAbsolute, join, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
+import { minifyHTML } from '@node-core/doc-kit/utils/html-minifier.mjs';
import {
build as viteBuild,
defaultClientConditions,
@@ -10,8 +11,6 @@ import {
mergeConfig,
} from 'vite';
-import { minifyHTML } from '../../../utils/html-minifier.mjs';
-
const VIRTUAL_PREFIX = 'virtual:doc-kit/';
const RESOLVED_VIRTUAL_PREFIX = '\0doc-kit:';
diff --git a/packages/core/src/generators/web/constants.mjs b/packages/react/src/html/constants.mjs
similarity index 100%
rename from packages/core/src/generators/web/constants.mjs
rename to packages/react/src/html/constants.mjs
diff --git a/packages/core/src/generators/web/generate.mjs b/packages/react/src/html/generate.mjs
similarity index 92%
rename from packages/core/src/generators/web/generate.mjs
rename to packages/react/src/html/generate.mjs
index 6903f67d..09ce5cef 100644
--- a/packages/core/src/generators/web/generate.mjs
+++ b/packages/react/src/html/generate.mjs
@@ -2,9 +2,10 @@
import { readFile } from 'node:fs/promises';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import { copyStaticAssets } from './utils/copying.mjs';
import { createCodeConverter, processBundles } from './utils/processing.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
/**
* Main generation function that sends per-page JSX code to the web bundler.
@@ -17,7 +18,7 @@ import getConfig from '../../utils/configuration/index.mjs';
* @type {import('./types').Generator['generate']}
*/
export async function generate(input) {
- const config = getConfig('web');
+ const config = getConfig('html');
const template = await readFile(config.templatePath, 'utf-8');
diff --git a/packages/core/src/generators/web/index.mjs b/packages/react/src/html/index.mjs
similarity index 93%
rename from packages/core/src/generators/web/index.mjs
rename to packages/react/src/html/index.mjs
index 69cfaeea..6be73932 100644
--- a/packages/core/src/generators/web/index.mjs
+++ b/packages/react/src/html/index.mjs
@@ -2,8 +2,9 @@
import { join } from 'node:path';
+import { GITHUB_EDIT_URL } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+
import { generate } from './generate.mjs';
-import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs';
/**
* Web generator - transforms JSX AST entries into complete web bundles.
@@ -25,14 +26,14 @@ import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs';
* @type {import('./types').Generator}
*/
export default {
- name: 'web',
+ name: 'html',
description: 'Generates HTML/CSS/JS bundles from JSX AST entries',
- dependsOn: '@node-core/doc-kit/jsx-ast',
+ dependsOn: '@nodejs/doc-kit-generator-react/jsx-ast',
/**
- * @param {import('../../utils/configuration/types').Configuration} config
+ * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration} config
*/
defaultConfiguration: config => ({
templatePath: join(import.meta.dirname, 'template.html'),
diff --git a/packages/react/src/html/template.html b/packages/react/src/html/template.html
new file mode 100644
index 00000000..b702d8e5
--- /dev/null
+++ b/packages/react/src/html/template.html
@@ -0,0 +1,25 @@
+
+
+
+
+
+ ${title}
+
+
+
+ ${head}
+
+
+
+
+
+
+
+ ${dehydrated}
+
+
+
diff --git a/packages/core/src/generators/web/types.d.ts b/packages/react/src/html/types.d.ts
similarity index 97%
rename from packages/core/src/generators/web/types.d.ts
rename to packages/react/src/html/types.d.ts
index e4e53d82..c701153c 100644
--- a/packages/core/src/generators/web/types.d.ts
+++ b/packages/react/src/html/types.d.ts
@@ -1,5 +1,5 @@
import type { JSXContent } from '../jsx-ast/utils/buildContent.mjs';
-import type { GlobalConfiguration } from '../../utils/configuration/types';
+import type { GlobalConfiguration } from '@node-core/doc-kit/utils/configuration/types';
import type SideBar from '@node-core/ui-components/Containers/Sidebar';
import type NavBar from '@node-core/ui-components/Containers/NavBar';
import type { ComponentProps } from 'preact';
diff --git a/packages/core/src/generators/web/ui/components/Banner.jsx b/packages/react/src/html/ui/components/Banner.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/Banner.jsx
rename to packages/react/src/html/ui/components/Banner.jsx
diff --git a/packages/core/src/generators/web/ui/components/CodeBox.jsx b/packages/react/src/html/ui/components/CodeBox.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/CodeBox.jsx
rename to packages/react/src/html/ui/components/CodeBox.jsx
diff --git a/packages/core/src/generators/web/ui/components/CodeTabs.jsx b/packages/react/src/html/ui/components/CodeTabs.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/CodeTabs.jsx
rename to packages/react/src/html/ui/components/CodeTabs.jsx
diff --git a/packages/core/src/generators/web/ui/components/Layout/index.jsx b/packages/react/src/html/ui/components/Layout/index.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/Layout/index.jsx
rename to packages/react/src/html/ui/components/Layout/index.jsx
diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx b/packages/react/src/html/ui/components/MetaBar/index.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/MetaBar/index.jsx
rename to packages/react/src/html/ui/components/MetaBar/index.jsx
diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.module.css b/packages/react/src/html/ui/components/MetaBar/index.module.css
similarity index 100%
rename from packages/core/src/generators/web/ui/components/MetaBar/index.module.css
rename to packages/react/src/html/ui/components/MetaBar/index.module.css
diff --git a/packages/core/src/generators/web/ui/components/NavBar.jsx b/packages/react/src/html/ui/components/NavBar.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/NavBar.jsx
rename to packages/react/src/html/ui/components/NavBar.jsx
diff --git a/packages/core/src/generators/web/ui/components/NoOp.jsx b/packages/react/src/html/ui/components/NoOp.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/NoOp.jsx
rename to packages/react/src/html/ui/components/NoOp.jsx
diff --git a/packages/core/src/generators/web/ui/components/SearchBox/index.jsx b/packages/react/src/html/ui/components/SearchBox/index.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/SearchBox/index.jsx
rename to packages/react/src/html/ui/components/SearchBox/index.jsx
diff --git a/packages/core/src/generators/web/ui/components/SearchBox/index.module.css b/packages/react/src/html/ui/components/SearchBox/index.module.css
similarity index 100%
rename from packages/core/src/generators/web/ui/components/SearchBox/index.module.css
rename to packages/react/src/html/ui/components/SearchBox/index.module.css
diff --git a/packages/core/src/generators/web/ui/components/SideBar/index.jsx b/packages/react/src/html/ui/components/SideBar/index.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/SideBar/index.jsx
rename to packages/react/src/html/ui/components/SideBar/index.jsx
diff --git a/packages/core/src/generators/web/ui/components/SideBar/index.module.css b/packages/react/src/html/ui/components/SideBar/index.module.css
similarity index 100%
rename from packages/core/src/generators/web/ui/components/SideBar/index.module.css
rename to packages/react/src/html/ui/components/SideBar/index.module.css
diff --git a/packages/core/src/generators/web/ui/components/ThemeToggle.jsx b/packages/react/src/html/ui/components/ThemeToggle.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/components/ThemeToggle.jsx
rename to packages/react/src/html/ui/components/ThemeToggle.jsx
diff --git a/packages/core/src/generators/web/ui/hooks/useBanners.mjs b/packages/react/src/html/ui/hooks/useBanners.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/hooks/useBanners.mjs
rename to packages/react/src/html/ui/hooks/useBanners.mjs
diff --git a/packages/core/src/generators/web/ui/hooks/useOrama.mjs b/packages/react/src/html/ui/hooks/useOrama.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/hooks/useOrama.mjs
rename to packages/react/src/html/ui/hooks/useOrama.mjs
diff --git a/packages/core/src/generators/web/ui/hooks/useTheme.mjs b/packages/react/src/html/ui/hooks/useTheme.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/hooks/useTheme.mjs
rename to packages/react/src/html/ui/hooks/useTheme.mjs
diff --git a/packages/core/src/generators/web/ui/index.css b/packages/react/src/html/ui/index.css
similarity index 100%
rename from packages/core/src/generators/web/ui/index.css
rename to packages/react/src/html/ui/index.css
diff --git a/packages/core/src/generators/web/ui/islands/loaders.mjs b/packages/react/src/html/ui/islands/loaders.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/islands/loaders.mjs
rename to packages/react/src/html/ui/islands/loaders.mjs
diff --git a/packages/core/src/generators/web/ui/islands/runtime.mjs b/packages/react/src/html/ui/islands/runtime.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/islands/runtime.mjs
rename to packages/react/src/html/ui/islands/runtime.mjs
diff --git a/packages/core/src/generators/web/ui/islands/withIsland.jsx b/packages/react/src/html/ui/islands/withIsland.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/islands/withIsland.jsx
rename to packages/react/src/html/ui/islands/withIsland.jsx
diff --git a/packages/core/src/generators/web/ui/package.json b/packages/react/src/html/ui/package.json
similarity index 100%
rename from packages/core/src/generators/web/ui/package.json
rename to packages/react/src/html/ui/package.json
diff --git a/packages/core/src/generators/web/ui/theme-script.mjs b/packages/react/src/html/ui/theme-script.mjs
similarity index 100%
rename from packages/core/src/generators/web/ui/theme-script.mjs
rename to packages/react/src/html/ui/theme-script.mjs
diff --git a/packages/core/src/generators/web/ui/types.d.ts b/packages/react/src/html/ui/types.d.ts
similarity index 89%
rename from packages/core/src/generators/web/ui/types.d.ts
rename to packages/react/src/html/ui/types.d.ts
index a47e6773..b7842f9e 100644
--- a/packages/core/src/generators/web/ui/types.d.ts
+++ b/packages/react/src/html/ui/types.d.ts
@@ -1,5 +1,5 @@
-import { GlobalConfiguration } from '../../../utils/configuration/types';
-import { MetadataEntry } from '../../metadata/types';
+import { GlobalConfiguration } from '@node-core/doc-kit/utils/configuration/types';
+import { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types';
import { Configuration } from '../types';
import { SemVer } from 'semver';
diff --git a/packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs b/packages/react/src/html/ui/utils/relativeOrAbsolute.mjs
similarity index 89%
rename from packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs
rename to packages/react/src/html/ui/utils/relativeOrAbsolute.mjs
index e08b4876..1ec84378 100644
--- a/packages/core/src/generators/web/ui/utils/relativeOrAbsolute.mjs
+++ b/packages/react/src/html/ui/utils/relativeOrAbsolute.mjs
@@ -1,4 +1,4 @@
-import { relative } from '../../../../utils/url.mjs';
+import { relative } from '@node-core/doc-kit/utils/url.mjs';
import { useAbsoluteURLs, baseURL } from '#theme/config';
diff --git a/packages/core/src/generators/web/ui/utils/renderLabel.jsx b/packages/react/src/html/ui/utils/renderLabel.jsx
similarity index 100%
rename from packages/core/src/generators/web/ui/utils/renderLabel.jsx
rename to packages/react/src/html/ui/utils/renderLabel.jsx
diff --git a/packages/core/src/generators/web/utils/__tests__/config.test.mjs b/packages/react/src/html/utils/__tests__/config.test.mjs
similarity index 97%
rename from packages/core/src/generators/web/utils/__tests__/config.test.mjs
rename to packages/react/src/html/utils/__tests__/config.test.mjs
index 4a64149b..b9f3bcfa 100644
--- a/packages/core/src/generators/web/utils/__tests__/config.test.mjs
+++ b/packages/react/src/html/utils/__tests__/config.test.mjs
@@ -1,10 +1,9 @@
import assert from 'node:assert/strict';
import { describe, it, mock } from 'node:test';
+import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs';
import { SemVer } from 'semver';
-import { setConfig } from '../../../../utils/configuration/index.mjs';
-
mock.module('@node-core/rehype-shiki', {
namedExports: {
LANGS: [
@@ -25,7 +24,7 @@ await setConfig({
{ version: new SemVer('22.0.0'), isLts: false, isCurrent: true },
],
generators: {
- web: {
+ html: {
title: 'Node.js',
repository: 'nodejs/node',
ref: 'main',
diff --git a/packages/core/src/generators/web/utils/__tests__/copying.test.mjs b/packages/react/src/html/utils/__tests__/copying.test.mjs
similarity index 95%
rename from packages/core/src/generators/web/utils/__tests__/copying.test.mjs
rename to packages/react/src/html/utils/__tests__/copying.test.mjs
index 385ab714..807b9b1f 100644
--- a/packages/core/src/generators/web/utils/__tests__/copying.test.mjs
+++ b/packages/react/src/html/utils/__tests__/copying.test.mjs
@@ -8,7 +8,7 @@ mock.module('node:fs/promises', {
});
const mockLogError = mock.fn();
-mock.module('../../../../logger/index.mjs', {
+mock.module('@node-core/doc-kit/logger/index.mjs', {
defaultExport: { error: mockLogError },
});
@@ -120,7 +120,7 @@ describe('copyStaticAssets', () => {
const logMessage = mockLogError.mock.calls[0].arguments[0];
assert.match(
logMessage,
- /\[web-generator\] Failed to copy asset from protected-file to \/out\/protected-file: Permission denied/
+ /\[html-generator\] Failed to copy asset from protected-file to \/out\/protected-file: Permission denied/
);
});
});
diff --git a/packages/core/src/generators/web/utils/__tests__/processing.test.mjs b/packages/react/src/html/utils/__tests__/processing.test.mjs
similarity index 96%
rename from packages/core/src/generators/web/utils/__tests__/processing.test.mjs
rename to packages/react/src/html/utils/__tests__/processing.test.mjs
index bd0b4c5b..985a49dc 100644
--- a/packages/core/src/generators/web/utils/__tests__/processing.test.mjs
+++ b/packages/react/src/html/utils/__tests__/processing.test.mjs
@@ -4,7 +4,8 @@ import { describe, it } from 'node:test';
import {
default as getConfig,
setConfig,
-} from '../../../../utils/configuration/index.mjs';
+} from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import {
buildHead,
populateWithEvaluation,
@@ -12,11 +13,11 @@ import {
} from '../processing.mjs';
await setConfig({
- target: ['web'],
+ target: ['html'],
version: 'v22.0.0',
changelog: [],
generators: {
- web: {
+ html: {
useAbsoluteURLs: false,
baseURL: 'https://nodejs.org/docs',
},
@@ -97,7 +98,7 @@ describe('resolvePageRoot', () => {
});
it('uses the configured base URL for synthetic pages with absolute URLs', async () => {
- getConfig('web').useAbsoluteURLs = true;
+ getConfig('html').useAbsoluteURLs = true;
const result = resolvePageRoot({
path: '/404',
@@ -105,7 +106,7 @@ describe('resolvePageRoot', () => {
});
assert.strictEqual(result, 'https://nodejs.org/docs/');
- getConfig('web').useAbsoluteURLs = false;
+ getConfig('html').useAbsoluteURLs = false;
});
});
diff --git a/packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs b/packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs
similarity index 90%
rename from packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs
rename to packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs
index 998d22e5..e191ff3c 100644
--- a/packages/core/src/generators/web/utils/__tests__/relativeOrAbsolute.test.mjs
+++ b/packages/react/src/html/utils/__tests__/relativeOrAbsolute.test.mjs
@@ -4,15 +4,16 @@ import { beforeEach, describe, it } from 'node:test';
import {
setConfig,
default as getConfig,
-} from '../../../../utils/configuration/index.mjs';
+} from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import { relativeOrAbsolute } from '../relativeOrAbsolute.mjs';
await setConfig({
- target: ['web'],
+ target: ['html'],
version: 'v22.0.0',
changelog: [],
generators: {
- web: {
+ html: {
useAbsoluteURLs: false,
baseURL: 'https://nodejs.org/docs',
},
@@ -21,7 +22,7 @@ await setConfig({
describe('relativeOrAbsolute (relative mode)', () => {
beforeEach(() => {
- getConfig('web').useAbsoluteURLs = false;
+ getConfig('html').useAbsoluteURLs = false;
});
it('returns a relative path from a nested page to root', () => {
@@ -47,7 +48,7 @@ describe('relativeOrAbsolute (relative mode)', () => {
describe('relativeOrAbsolute (absolute mode)', () => {
beforeEach(() => {
- getConfig('web').useAbsoluteURLs = true;
+ getConfig('html').useAbsoluteURLs = true;
});
it('returns an absolute URL to root', () => {
diff --git a/packages/core/src/generators/web/utils/config.mjs b/packages/react/src/html/utils/config.mjs
similarity index 90%
rename from packages/core/src/generators/web/utils/config.mjs
rename to packages/react/src/html/utils/config.mjs
index 042f1fcc..b32f937a 100644
--- a/packages/core/src/generators/web/utils/config.mjs
+++ b/packages/react/src/html/utils/config.mjs
@@ -1,11 +1,11 @@
'use strict';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+import { getVersionFromSemVer } from '@node-core/doc-kit/utils/generators.mjs';
+import { omitKeys } from '@node-core/doc-kit/utils/misc.mjs';
import { LANGS } from '@node-core/rehype-shiki';
-import getConfig from '../../../utils/configuration/index.mjs';
-import { populate } from '../../../utils/configuration/templates.mjs';
-import { getVersionFromSemVer } from '../../../utils/generators.mjs';
-import { omitKeys } from '../../../utils/misc.mjs';
import { getSortedHeadNodes } from '../../jsx-ast/utils/getSortedHeadNodes.mjs';
/**
@@ -74,7 +74,7 @@ export function buildLanguageDisplayNameMap() {
* @returns {string} JavaScript source code string with named exports
*/
export default function createConfigSource(input, server = false) {
- const { version: configVersion, ...config } = getConfig('web');
+ const { version: configVersion, ...config } = getConfig('html');
const editURL = populate(config.editURL, {
...config,
diff --git a/packages/core/src/generators/web/utils/copying.mjs b/packages/react/src/html/utils/copying.mjs
similarity index 86%
rename from packages/core/src/generators/web/utils/copying.mjs
rename to packages/react/src/html/utils/copying.mjs
index 20bd5d12..084b6414 100644
--- a/packages/core/src/generators/web/utils/copying.mjs
+++ b/packages/react/src/html/utils/copying.mjs
@@ -1,7 +1,7 @@
import { cp } from 'node:fs/promises';
import { join, basename } from 'node:path';
-import logger from '../../../logger/index.mjs';
+import logger from '@node-core/doc-kit/logger/index.mjs';
/**
* Copies static directories/files defined in `pathsToCopy` to the output directory.
@@ -28,7 +28,7 @@ export async function copyStaticAssets(config) {
} catch (err) {
if (err.code !== 'ENOENT') {
logger.error(
- `[web-generator] Failed to copy asset from ${src} to ${dest}: ${err.message}`
+ `[html-generator] Failed to copy asset from ${src} to ${dest}: ${err.message}`
);
}
}
diff --git a/packages/core/src/generators/web/utils/generate.mjs b/packages/react/src/html/utils/generate.mjs
similarity index 96%
rename from packages/core/src/generators/web/utils/generate.mjs
rename to packages/react/src/html/utils/generate.mjs
index e3c13c74..0ef403df 100644
--- a/packages/core/src/generators/web/utils/generate.mjs
+++ b/packages/react/src/html/utils/generate.mjs
@@ -1,6 +1,7 @@
import { resolve } from 'node:path';
-import getConfig from '../../../utils/configuration/index.mjs';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import { JSX_IMPORTS, ROOT } from '../constants.mjs';
/**
@@ -50,7 +51,7 @@ export const createImportDeclaration = (
*/
export default () => {
// User-configured components (for JSX-in-MDX), merged with the built-ins.
- const { components } = getConfig('web');
+ const { components } = getConfig('html');
const componentImports = [
...Object.values(JSX_IMPORTS),
diff --git a/packages/core/src/generators/web/utils/processing.mjs b/packages/react/src/html/utils/processing.mjs
similarity index 85%
rename from packages/core/src/generators/web/utils/processing.mjs
rename to packages/react/src/html/utils/processing.mjs
index 73263c02..cfbfba1d 100644
--- a/packages/core/src/generators/web/utils/processing.mjs
+++ b/packages/react/src/html/utils/processing.mjs
@@ -1,8 +1,9 @@
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+
import createConfigSource from './config.mjs';
import createProgramBuilder from './generate.mjs';
import { relativeOrAbsolute } from './relativeOrAbsolute.mjs';
-import getConfig from '../../../utils/configuration/index.mjs';
-import { populate } from '../../../utils/configuration/templates.mjs';
import { resolveBundler } from '../bundlers/index.mjs';
import { SPECULATION_RULES } from '../constants.mjs';
import { THEME_SCRIPT } from '../ui/theme-script.mjs';
@@ -10,7 +11,7 @@ import { THEME_SCRIPT } from '../ui/theme-script.mjs';
/**
* Creates the virtual imports for one bundle target.
*
- * @param {Array<{ data: import('../../metadata/types').MetadataEntry }>} sidebarEntries
+ * @param {Array<{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }>} sidebarEntries
* @param {Record} virtualImports
* @param {boolean} server
* @returns {Record}
@@ -38,12 +39,12 @@ export const populateWithEvaluation = (template, config) => {
};
/**
- * @param {import('../../metadata/types').MetadataEntry} data
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} data
* @returns {string}
*/
export const resolvePageRoot = data => {
if (data.synthetic === true) {
- const { baseURL, useAbsoluteURLs } = getConfig('web');
+ const { baseURL, useAbsoluteURLs } = getConfig('html');
return useAbsoluteURLs ? String(baseURL).replace(/\/?$/, '/') : '/';
}
@@ -91,7 +92,7 @@ export const buildHead = ({ meta = [], links = [], html = [] }) =>
* string upstream (in the `jsx-ast` worker), so the heavy AST never reaches
* the main thread — only the code string and page metadata stream in here.
*
- * @returns {{ add: (item: { data: import('../../metadata/types').MetadataEntry, code: string }) => void, serverCodeMap: Map, clientCodeMap: Map }}
+ * @returns {{ add: (item: { data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry, code: string }) => void, serverCodeMap: Map, clientCodeMap: Map }}
*/
export function createCodeConverter() {
const { buildServerProgram, clientProgram } = createProgramBuilder();
@@ -103,7 +104,7 @@ export function createCodeConverter() {
/**
* Records the server/client programs for a single page's JSX code.
*
- * @param {{ data: import('../../metadata/types').MetadataEntry, code: string }} item
+ * @param {{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry, code: string }} item
*/
add: ({ data, code }) => {
const fileName = `${data.api}.jsx`;
@@ -128,8 +129,8 @@ export function createCodeConverter() {
* @param {object} params
* @param {Map} params.serverCodeMap - Server-side code per page.
* @param {Map} params.clientCodeMap - Client-side code per page.
- * @param {Array} params.datas - Per-page metadata, in render order.
- * @param {Array<{ data: import('../../metadata/types').MetadataEntry }>} params.sidebarEntries - Entries used to build the sidebar page list (real module pages only).
+ * @param {Array} params.datas - Per-page metadata, in render order.
+ * @param {Array<{ data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }>} params.sidebarEntries - Entries used to build the sidebar page list (real module pages only).
* @param {string} params.template - The HTML template string for the output pages.
*/
export async function processBundles({
@@ -139,7 +140,7 @@ export async function processBundles({
sidebarEntries,
template,
}) {
- const config = getConfig('web');
+ const config = getConfig('html');
const bundler = await resolveBundler(config.bundler);
const serverPages = await bundler.render({
diff --git a/packages/core/src/generators/web/utils/relativeOrAbsolute.mjs b/packages/react/src/html/utils/relativeOrAbsolute.mjs
similarity index 69%
rename from packages/core/src/generators/web/utils/relativeOrAbsolute.mjs
rename to packages/react/src/html/utils/relativeOrAbsolute.mjs
index a37be0e3..cc85803d 100644
--- a/packages/core/src/generators/web/utils/relativeOrAbsolute.mjs
+++ b/packages/react/src/html/utils/relativeOrAbsolute.mjs
@@ -1,5 +1,5 @@
-import getConfig from '../../../utils/configuration/index.mjs';
-import { relative } from '../../../utils/url.mjs';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { relative } from '@node-core/doc-kit/utils/url.mjs';
/**
* Returns an absolute URL (based on baseURL) or a relative URL,
@@ -10,7 +10,7 @@ import { relative } from '../../../utils/url.mjs';
* @returns {string}
*/
export const relativeOrAbsolute = (to, from) => {
- const { useAbsoluteURLs, baseURL } = getConfig('web');
+ const { useAbsoluteURLs, baseURL } = getConfig('html');
return useAbsoluteURLs
? new URL(`.${to}`, baseURL.replace(/\/?$/, '/')).href
diff --git a/packages/core/src/generators/jsx-ast/README.md b/packages/react/src/jsx-ast/README.md
similarity index 100%
rename from packages/core/src/generators/jsx-ast/README.md
rename to packages/react/src/jsx-ast/README.md
diff --git a/packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs b/packages/react/src/jsx-ast/__tests__/generate.test.mjs
similarity index 96%
rename from packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs
rename to packages/react/src/jsx-ast/__tests__/generate.test.mjs
index e1f52e76..4894c7e7 100644
--- a/packages/core/src/generators/jsx-ast/__tests__/generate.test.mjs
+++ b/packages/react/src/jsx-ast/__tests__/generate.test.mjs
@@ -1,7 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
-import getConfig, { setConfig } from '../../../utils/configuration/index.mjs';
+import getConfig, {
+ setConfig,
+} from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import { generate, processChunk } from '../generate.mjs';
const createEntry = (api, name, { stabilityIndex = '2' } = {}) => {
diff --git a/packages/core/src/generators/jsx-ast/constants.mjs b/packages/react/src/jsx-ast/constants.mjs
similarity index 99%
rename from packages/core/src/generators/jsx-ast/constants.mjs
rename to packages/react/src/jsx-ast/constants.mjs
index dddad667..ffeec38c 100644
--- a/packages/core/src/generators/jsx-ast/constants.mjs
+++ b/packages/react/src/jsx-ast/constants.mjs
@@ -1,4 +1,4 @@
-import { JSX_IMPORTS } from '../web/constants.mjs';
+import { JSX_IMPORTS } from '../html/constants.mjs';
/**
* UI classes for Node.js API stability levels
diff --git a/packages/core/src/generators/jsx-ast/generate.mjs b/packages/react/src/jsx-ast/generate.mjs
similarity index 91%
rename from packages/core/src/generators/jsx-ast/generate.mjs
rename to packages/react/src/jsx-ast/generate.mjs
index 055e0efb..89f69e93 100644
--- a/packages/core/src/generators/jsx-ast/generate.mjs
+++ b/packages/react/src/jsx-ast/generate.mjs
@@ -1,3 +1,5 @@
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs';
import { jsx, toJs } from 'estree-util-to-js';
import buildContent from './utils/buildContent.mjs';
@@ -5,8 +7,6 @@ import { getSortedHeadNodes } from './utils/getSortedHeadNodes.mjs';
import { buildNotFoundPage } from './utils/synthetic/404.mjs';
import { buildAllPage } from './utils/synthetic/all.mjs';
import { buildIndexPage } from './utils/synthetic/index.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { groupNodesByModule } from '../../utils/generators.mjs';
/**
* Builds the `{ head, entries }` page descriptors for all configured synthetic
@@ -14,7 +14,7 @@ import { groupNodesByModule } from '../../utils/generators.mjs';
* runs later in a worker (via `processChunk`), so the very large synthetic
* `all` page is never built on the main thread.
*
- * @param {Array} input
+ * @param {Array} input
*/
const buildSyntheticDescriptors = input => {
const config = getConfig('jsx-ast');
diff --git a/packages/core/src/generators/jsx-ast/index.mjs b/packages/react/src/jsx-ast/index.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/index.mjs
rename to packages/react/src/jsx-ast/index.mjs
diff --git a/packages/core/src/generators/jsx-ast/types.d.ts b/packages/react/src/jsx-ast/types.d.ts
similarity index 82%
rename from packages/core/src/generators/jsx-ast/types.d.ts
rename to packages/react/src/jsx-ast/types.d.ts
index 672c5a4f..cffbb835 100644
--- a/packages/core/src/generators/jsx-ast/types.d.ts
+++ b/packages/react/src/jsx-ast/types.d.ts
@@ -1,4 +1,4 @@
-import type { MetadataEntry } from '../metadata/types';
+import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types';
import type { JSXContent } from './utils/buildContent.mjs';
export type Generator = GeneratorMetadata<
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/ast.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/ast.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/ast.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/ast.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/buildBarProps.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs
similarity index 95%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs
index afb86405..e1c21538 100644
--- a/packages/core/src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs
+++ b/packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs
@@ -1,7 +1,8 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
-import { setConfig } from '../../../../utils/configuration/index.mjs';
+import { setConfig } from '@node-core/doc-kit/utils/configuration/index.mjs';
+
import { transformHeadingNode } from '../buildContent.mjs';
const heading = {
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/overloads.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/overloads.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/overloads.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/overloads.test.mjs
diff --git a/packages/core/src/utils/__tests__/remark.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/remark.test.mjs
similarity index 100%
rename from packages/core/src/utils/__tests__/remark.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/remark.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/signature.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/signature.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/signature.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/signature.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs b/packages/react/src/jsx-ast/utils/__tests__/types.test.mjs
similarity index 99%
rename from packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs
rename to packages/react/src/jsx-ast/utils/__tests__/types.test.mjs
index 0c4a7c3e..de963d4f 100644
--- a/packages/core/src/generators/jsx-ast/utils/__tests__/types.test.mjs
+++ b/packages/react/src/jsx-ast/utils/__tests__/types.test.mjs
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { describe, it, mock } from 'node:test';
// Mock remark
-mock.module('../../../../utils/remark.mjs', {
+mock.module('../remark.mjs', {
namedExports: {
getRemarkRecma: () => ({
runSync: () => ({
diff --git a/packages/core/src/generators/jsx-ast/utils/ast.mjs b/packages/react/src/jsx-ast/utils/ast.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/ast.mjs
rename to packages/react/src/jsx-ast/utils/ast.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs b/packages/react/src/jsx-ast/utils/buildBarProps.mjs
similarity index 83%
rename from packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs
rename to packages/react/src/jsx-ast/utils/buildBarProps.mjs
index d535c30a..367d96ea 100644
--- a/packages/core/src/generators/jsx-ast/utils/buildBarProps.mjs
+++ b/packages/react/src/jsx-ast/utils/buildBarProps.mjs
@@ -12,7 +12,7 @@ const FUNCTION_HEADING_TYPES = new Set(['method', 'ctor', 'classMethod']);
/**
* Generate a combined plain text string from all MDAST entries for estimating reading time.
*
- * @param {Array} entries - API documentation entries
+ * @param {Array} entries - API documentation entries
*/
export const extractTextContent = entries => {
return entries.reduce((acc, entry) => {
@@ -25,7 +25,7 @@ export const extractTextContent = entries => {
/**
* Determines if an entry should be included in the Table of Contents.
- * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry
*/
const shouldIncludeEntryInToC = ({ heading }) =>
// Only include headings with text,
@@ -41,7 +41,7 @@ const shouldIncludeEntryInToC = ({ heading }) =>
* other headings keep their plain text, with CLI flags / env vars and leading
* prefixes (i.e. `Class:`) stripped.
*
- * @param {import('../../metadata/types').HeadingData} data
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingData} data
*/
const headingLabel = data => {
if (FUNCTION_HEADING_TYPES.has(data.type)) {
@@ -70,7 +70,7 @@ const headingLabel = data => {
/**
* Extracts and formats heading information from an API documentation entry.
- * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry
*/
const extractHeading = entry => {
const data = entry.heading.data;
@@ -88,7 +88,7 @@ const extractHeading = entry => {
* Build the list of heading metadata for sidebar navigation. Overload headings
* are dropped so each function contributes a single entry.
*
- * @param {Array} entries - All API metadata entries
+ * @param {Array} entries - All API metadata entries
*/
export const extractHeadings = entries =>
entries
diff --git a/packages/core/src/generators/jsx-ast/utils/buildContent.mjs b/packages/react/src/jsx-ast/utils/buildContent.mjs
similarity index 83%
rename from packages/core/src/generators/jsx-ast/utils/buildContent.mjs
rename to packages/react/src/jsx-ast/utils/buildContent.mjs
index dd621eec..3b1ac769 100644
--- a/packages/core/src/generators/jsx-ast/utils/buildContent.mjs
+++ b/packages/react/src/jsx-ast/utils/buildContent.mjs
@@ -1,5 +1,13 @@
'use strict';
+import { enforceArray } from '@node-core/doc-kit/utils/array.mjs';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import {
+ GITHUB_BLOB_URL,
+ populate,
+} from '@node-core/doc-kit/utils/configuration/templates.mjs';
+import { omitKeys } from '@node-core/doc-kit/utils/misc.mjs';
+import { UNIST } from '@node-core/doc-kit/utils/queries/index.mjs';
import { h as createElement } from 'hastscript';
import { slice } from 'mdast-util-slice-markdown';
import readingTime from 'reading-time';
@@ -9,9 +17,8 @@ import { SKIP, visit } from 'unist-util-visit';
import { createJSXElement } from './ast.mjs';
import { extractHeadings, extractTextContent } from './buildBarProps.mjs';
import { annotateOverloads } from './overloads.mjs';
-import { enforceArray } from '../../../utils/array.mjs';
-import { omitKeys } from '../../../utils/misc.mjs';
-import { JSX_IMPORTS } from '../../web/constants.mjs';
+import { getRemarkRecma as remark } from './remark.mjs';
+import { JSX_IMPORTS } from '../../html/constants.mjs';
import {
STABILITY_LEVELS,
LIFECYCLE_LABELS,
@@ -27,17 +34,10 @@ import {
createSignatureTable,
getFullName,
} from './signature.mjs';
-import getConfig from '../../../utils/configuration/index.mjs';
-import {
- GITHUB_BLOB_URL,
- populate,
-} from '../../../utils/configuration/templates.mjs';
-import { UNIST } from '../../../utils/queries/index.mjs';
-import { getRemarkRecma as remark } from '../../../utils/remark.mjs';
/**
* Processes lifecycle and change history data into a sorted array of change entries.
- * @param {import('../../metadata/types').MetadataEntry} entry - The metadata entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The metadata entry
*/
export const gatherChangeEntries = entry => {
// Lifecycle changes (e.g., added, deprecated)
@@ -61,7 +61,7 @@ export const gatherChangeEntries = entry => {
/**
* Creates a JSX ChangeHistory element or returns null if no changes.
- * @param {import('../../metadata/types').MetadataEntry} entry - The metadata entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The metadata entry
*/
export const createChangeElement = entry => {
const changes = gatherChangeEntries(entry);
@@ -128,7 +128,7 @@ export const extractHeadingContent = content => {
/**
* Creates a heading wrapper element with anchors, icons, and optional change history.
- * @param {import('../../metadata/types').HeadingNode} content - The content node to extract text from
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} content - The content node to extract text from
* @param {import('unist').Node|null} changeElement - The change history element, if available
*/
export const createHeadingElement = (content, changeElement) => {
@@ -166,7 +166,7 @@ export const createHeadingElement = (content, changeElement) => {
/**
* Converts a stability note node to an AlertBox JSX element
- * @param {import('../../metadata/types').StabilityNode} node - The stability node to transform
+ * @param {import('@node-core/doc-kit/generators/metadata/types').StabilityNode} node - The stability node to transform
* @param {number} index - The index of the node in its parent's children array
* @param {import('unist').Parent} parent - The parent node containing the stability node
*/
@@ -200,8 +200,8 @@ const getLevelFromDeprecationType = typeText => {
/**
* Transforms a heading node by injecting metadata, source links, and signatures.
- * @param {import('../../metadata/types').MetadataEntry} entry - The API metadata entry
- * @param {import('../../metadata/types').HeadingNode} node - The heading node to transform
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The API metadata entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} node - The heading node to transform
* @param {number} index - The index of the node in its parent's children array
* @param {import('unist').Parent} parent - The parent node containing the heading
*/
@@ -250,7 +250,7 @@ export const transformHeadingNode = async (entry, node, index, parent) => {
/**
* Processes a single API documentation entry's content
- * @param {import('../../metadata/types').MetadataEntry} entry - The API metadata entry to process
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry - The API metadata entry to process
*/
export const processEntry = entry => {
// Visit and transform stability nodes
@@ -276,7 +276,7 @@ export const processEntry = entry => {
/**
* Builds the overall document layout tree
- * @param {Array} entries - API documentation metadata entries
+ * @param {Array} entries - API documentation metadata entries
* @param {Object} metadata - Raw page metadata from the head entry
*/
export const createDocumentLayout = (entries, metadata) => {
@@ -295,11 +295,11 @@ export const createDocumentLayout = (entries, metadata) => {
};
/**
- * @typedef {import('estree').Node & { data: import('../../metadata/types').MetadataEntry }} JSXContent
+ * @typedef {import('estree').Node & { data: import('@node-core/doc-kit/generators/metadata/types').MetadataEntry }} JSXContent
*
* Transforms API metadata entries into processed MDX content
- * @param {Array} metadataEntries - API documentation metadata entries
- * @param {import('../../metadata/types').MetadataEntry} head - Main API metadata entry with version information
+ * @param {Array} metadataEntries - API documentation metadata entries
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} head - Main API metadata entry with version information
* @returns {Promise}
*/
const buildContent = async (metadataEntries, head) => {
diff --git a/packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs b/packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs
similarity index 66%
rename from packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs
rename to packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs
index c0f0c54c..b28460cc 100644
--- a/packages/core/src/generators/jsx-ast/utils/getSortedHeadNodes.mjs
+++ b/packages/react/src/jsx-ast/utils/getSortedHeadNodes.mjs
@@ -4,8 +4,8 @@ import { OVERRIDDEN_POSITIONS } from '../constants.mjs';
/**
* Sorts entries by OVERRIDDEN_POSITIONS and then heading name.
- * @param {import('../../metadata/types').MetadataEntry} a
- * @param {import('../../metadata/types').MetadataEntry} b
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} a
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} b
* @returns {number}
*/
const headingSortFn = (a, b) => {
@@ -29,8 +29,8 @@ const headingSortFn = (a, b) => {
/**
* Filters and sorts entries by OVERRIDDEN_POSITIONS and then heading name.
- * @param {Array} entries
- * @returns {Array}
+ * @param {Array} entries
+ * @returns {Array}
*/
export const getSortedHeadNodes = entries =>
entries.filter(node => node.heading.depth === 1).toSorted(headingSortFn);
diff --git a/packages/core/src/generators/jsx-ast/utils/overloads.mjs b/packages/react/src/jsx-ast/utils/overloads.mjs
similarity index 78%
rename from packages/core/src/generators/jsx-ast/utils/overloads.mjs
rename to packages/react/src/jsx-ast/utils/overloads.mjs
index b35ad093..f6feee03 100644
--- a/packages/core/src/generators/jsx-ast/utils/overloads.mjs
+++ b/packages/react/src/jsx-ast/utils/overloads.mjs
@@ -8,8 +8,8 @@ const OVERLOADABLE_TYPES = new Set(['method', 'ctor', 'classMethod']);
* Two headings document the same function (i.e. are overloads of one another)
* when they sit at the same depth and share the same resolved name and type.
*
- * @param {import('../../metadata/types').HeadingNode} a
- * @param {import('../../metadata/types').HeadingNode} b
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} a
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} b
*/
const isSameFunction = (a, b) =>
a.depth === b.depth &&
@@ -26,8 +26,8 @@ const isSameFunction = (a, b) =>
* rendering in full on the page. The first (most stable) heading is left as-is,
* and the ToC links to its existing anchor.
*
- * @param {Array} entries - Page entries, in render order.
- * @returns {Array} The same entries (mutated).
+ * @param {Array} entries - Page entries, in render order.
+ * @returns {Array} The same entries (mutated).
*/
export const annotateOverloads = entries => {
for (let i = 0; i < entries.length; i++) {
diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/__tests__/alerts.test.mjs b/packages/react/src/jsx-ast/utils/plugins/__tests__/alerts.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/plugins/__tests__/alerts.test.mjs
rename to packages/react/src/jsx-ast/utils/plugins/__tests__/alerts.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/__tests__/transformer.test.mjs b/packages/react/src/jsx-ast/utils/plugins/__tests__/transformer.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/plugins/__tests__/transformer.test.mjs
rename to packages/react/src/jsx-ast/utils/plugins/__tests__/transformer.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs b/packages/react/src/jsx-ast/utils/plugins/alerts.mjs
similarity index 97%
rename from packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs
rename to packages/react/src/jsx-ast/utils/plugins/alerts.mjs
index 1abe1940..4ede03e5 100644
--- a/packages/core/src/generators/jsx-ast/utils/plugins/alerts.mjs
+++ b/packages/react/src/jsx-ast/utils/plugins/alerts.mjs
@@ -2,7 +2,7 @@
import { SKIP, visit } from 'unist-util-visit';
-import { JSX_IMPORTS } from '../../../web/constants.mjs';
+import { JSX_IMPORTS } from '../../../html/constants.mjs';
import { ALERT_MARKER, GITHUB_ALERT_TYPES } from '../../constants.mjs';
import { createJSXElement } from '../ast.mjs';
diff --git a/packages/core/src/generators/jsx-ast/utils/plugins/transformer.mjs b/packages/react/src/jsx-ast/utils/plugins/transformer.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/plugins/transformer.mjs
rename to packages/react/src/jsx-ast/utils/plugins/transformer.mjs
diff --git a/packages/react/src/jsx-ast/utils/remark.mjs b/packages/react/src/jsx-ast/utils/remark.mjs
new file mode 100644
index 00000000..889244f3
--- /dev/null
+++ b/packages/react/src/jsx-ast/utils/remark.mjs
@@ -0,0 +1,80 @@
+'use strict';
+
+import { highlighter } from '@node-core/doc-kit/utils/highlighter.mjs';
+import { lazy } from '@node-core/doc-kit/utils/misc.mjs';
+import { typeAnnotationToHighlightedHast } from '@node-core/doc-kit/utils/type-annotations/hast.mjs';
+import rehypeShikiji from '@node-core/rehype-shiki/plugin';
+import recmaJsx from 'recma-jsx';
+import recmaStringify from 'recma-stringify';
+import rehypeRaw from 'rehype-raw';
+import rehypeRecma from 'rehype-recma';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+
+import { AST_NODE_TYPES } from '../constants.mjs';
+import transformAlerts from './plugins/alerts.mjs';
+import transformElements from './plugins/transformer.mjs';
+
+const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)];
+const codeMetaProperty = 'codeMeta';
+
+/**
+ * Stores fenced code metadata on properties before rehypeRaw reparses the tree.
+ */
+const preserveCodeMeta = () => tree => {
+ visit(tree, 'element', node => {
+ const meta = node.data?.meta;
+
+ if (node.tagName === 'code' && typeof meta === 'string') {
+ node.properties ||= {};
+ node.properties[codeMetaProperty] = meta;
+ }
+ });
+};
+
+/**
+ * Restores fenced code metadata so the Shiki plugin can read displayName.
+ */
+const restoreCodeMeta = () => tree => {
+ visit(tree, 'element', node => {
+ const meta = node.properties?.[codeMetaProperty];
+
+ if (node.tagName === 'code' && typeof meta === 'string') {
+ node.data = { ...node.data, meta };
+ delete node.properties[codeMetaProperty];
+ }
+ });
+};
+
+const singletonShiki = await rehypeShikiji({ highlighter });
+
+/**
+ * Retrieves an instance of Remark configured to output JSX code.
+ * including parsing Code Boxes with syntax highlighting
+ */
+export const getRemarkRecma = lazy(() =>
+ unified()
+ .use(remarkParse)
+ .use(transformAlerts)
+ // We make Rehype ignore existing HTML nodes, and JSX nodes
+ // as these are nodes we manually created during the generation process
+ // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
+ // and we trust the sources of the Markdown files
+ .use(remarkRehype, {
+ allowDangerousHtml: true,
+ passThrough,
+ // The web pipeline gets Shiki-highlighted types with embedded links
+ handlers: { typeAnnotation: typeAnnotationToHighlightedHast },
+ })
+ .use(preserveCodeMeta)
+ // Any `raw` HTML in the markdown must be converted to AST in order for Recma to understand it
+ .use(rehypeRaw, { passThrough })
+ .use(restoreCodeMeta)
+ .use(() => singletonShiki)
+ .use(transformElements)
+ .use(rehypeRecma)
+ .use(recmaJsx)
+ .use(recmaStringify)
+);
diff --git a/packages/core/src/generators/jsx-ast/utils/signature.mjs b/packages/react/src/jsx-ast/utils/signature.mjs
similarity index 83%
rename from packages/core/src/generators/jsx-ast/utils/signature.mjs
rename to packages/react/src/jsx-ast/utils/signature.mjs
index f7220d02..8ffedcc4 100644
--- a/packages/core/src/generators/jsx-ast/utils/signature.mjs
+++ b/packages/react/src/jsx-ast/utils/signature.mjs
@@ -1,18 +1,18 @@
+import { highlighter } from '@node-core/doc-kit/utils/highlighter.mjs';
+import { UNIST } from '@node-core/doc-kit/utils/queries/index.mjs';
+import { parseListItem } from '@node-core/doc-kit/utils/signature/parseList.mjs';
+import parseSignature from '@node-core/doc-kit/utils/signature/parseSignature.mjs';
import { h as createElement } from 'hastscript';
import { createJSXElement } from './ast.mjs';
import { parseListIntoProperties } from './types.mjs';
-import { highlighter } from '../../../utils/highlighter.mjs';
-import { UNIST } from '../../../utils/queries/index.mjs';
-import { parseListItem } from '../../../utils/signature/parseList.mjs';
-import parseSignature from '../../../utils/signature/parseSignature.mjs';
-import { JSX_IMPORTS } from '../../web/constants.mjs';
+import { JSX_IMPORTS } from '../../html/constants.mjs';
/**
* Generates a string representation of a function or class signature.
*
* @param {string} functionName - The name of the function or class.
- * @param {import('../../../utils/signature/types').MethodSignature} signature - The parsed signature object.
+ * @param {import('@node-core/doc-kit/utils/signature/types').MethodSignature} signature - The parsed signature object.
* @param {string} prefix - Optional prefix, i.e. `'new '` for constructors.
*/
export const generateSignature = (
@@ -52,7 +52,7 @@ export const generateSignature = (
* Creates a syntax-highlighted code block for a signature using rehype-shiki.
*
* @param {string} functionName - The function name to display.
- * @param {import('../../../utils/signature/types').MethodSignature} signature - Signature object with parameter and return type info.
+ * @param {import('@node-core/doc-kit/utils/signature/types').MethodSignature} signature - Signature object with parameter and return type info.
* @param {string} prefix - Optional prefix like `'new '`.
*/
export const createSignatureCodeBlock = (functionName, signature, prefix) => {
@@ -66,7 +66,7 @@ export const createSignatureCodeBlock = (functionName, signature, prefix) => {
* Infers the "real" function name from a heading node.
* Useful when auto-generated headings differ from code tokens.
*
- * @param {import('../../metadata/types').HeadingData} heading - Metadata with name and text fields.
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingData} heading - Metadata with name and text fields.
* @param {any} fallback - Fallback value if inference fails.
*/
export const getFullName = ({ name, text }, fallback = name) => {
@@ -91,7 +91,7 @@ export const getFullName = ({ name, text }, fallback = name) => {
* Mutates the `children` array by injecting the signature HAST node.
*
* @param {import('@types/mdast').Parent} parent - The parent MDAST node (usually a section).
- * @param {import('../../metadata/types').HeadingNode} heading - The heading node with metadata.
+ * @param {import('@node-core/doc-kit/generators/metadata/types').HeadingNode} heading - The heading node with metadata.
* @param {number} idx - The index at which the heading occurs in `parent.children`.
*/
export const insertSignatureCodeBlock = ({ children }, { data }, idx) => {
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/404.mjs b/packages/react/src/jsx-ast/utils/synthetic/404.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/404.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/404.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/404.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/404.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/all.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/all.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/all.test.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/all.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/index.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/index.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/index.test.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/index.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs b/packages/react/src/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/__tests__/synthetic.test.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs b/packages/react/src/jsx-ast/utils/synthetic/all.mjs
similarity index 70%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/all.mjs
index a25894ed..79537e4f 100644
--- a/packages/core/src/generators/jsx-ast/utils/synthetic/all.mjs
+++ b/packages/react/src/jsx-ast/utils/synthetic/all.mjs
@@ -5,7 +5,7 @@ import { createSyntheticHead } from './synthetic.mjs';
/**
* Builds the page descriptor for `all.html`
*
- * @param {Array} entries
+ * @param {Array} entries
*/
export const buildAllPage = entries => ({
head: createSyntheticHead('all', 'All'),
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs b/packages/react/src/jsx-ast/utils/synthetic/index.mjs
similarity index 88%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/index.mjs
index 423d11a0..f040e98b 100644
--- a/packages/core/src/generators/jsx-ast/utils/synthetic/index.mjs
+++ b/packages/react/src/jsx-ast/utils/synthetic/index.mjs
@@ -3,7 +3,7 @@
import { h as createElement } from 'hastscript';
import { createSyntheticHead, wrapAsEntry } from './synthetic.mjs';
-import { JSX_IMPORTS } from '../../../web/constants.mjs';
+import { JSX_IMPORTS } from '../../../html/constants.mjs';
import { createJSXElement } from '../ast.mjs';
import { getSortedHeadNodes } from '../getSortedHeadNodes.mjs';
@@ -28,7 +28,7 @@ const getStabilityBadgeKind = index =>
* Builds the Stability Overview table from module heads that declare a
* top-level stability index, mirroring the `legacy-html-all` overview.
*
- * @param {Array} headEntries
+ * @param {Array} headEntries
*/
export const buildStabilityOverview = headEntries =>
createElement('table', [
@@ -64,7 +64,7 @@ export const buildStabilityOverview = headEntries =>
/**
* Builds the page descriptor for `index.html`
*
- * @param {Array} entries
+ * @param {Array} entries
*/
export const buildIndexPage = entries => {
const head = createSyntheticHead('index', 'Index');
diff --git a/packages/core/src/generators/jsx-ast/utils/synthetic/synthetic.mjs b/packages/react/src/jsx-ast/utils/synthetic/synthetic.mjs
similarity index 100%
rename from packages/core/src/generators/jsx-ast/utils/synthetic/synthetic.mjs
rename to packages/react/src/jsx-ast/utils/synthetic/synthetic.mjs
diff --git a/packages/core/src/generators/jsx-ast/utils/types.mjs b/packages/react/src/jsx-ast/utils/types.mjs
similarity index 90%
rename from packages/core/src/generators/jsx-ast/utils/types.mjs
rename to packages/react/src/jsx-ast/utils/types.mjs
index 706f7dd9..1d5867b8 100644
--- a/packages/core/src/generators/jsx-ast/utils/types.mjs
+++ b/packages/react/src/jsx-ast/utils/types.mjs
@@ -1,9 +1,9 @@
+import { QUERIES, UNIST } from '@node-core/doc-kit/utils/queries/index.mjs';
+import { DEFAULT_EXPRESSION } from '@node-core/doc-kit/utils/signature/constants.mjs';
+import { transformNodesToString } from '@node-core/doc-kit/utils/unist.mjs';
import { u as createTree } from 'unist-builder';
-import { QUERIES, UNIST } from '../../../utils/queries/index.mjs';
-import { getRemarkRecma as remark } from '../../../utils/remark.mjs';
-import { DEFAULT_EXPRESSION } from '../../../utils/signature/constants.mjs';
-import { transformNodesToString } from '../../../utils/unist.mjs';
+import { getRemarkRecma as remark } from './remark.mjs';
import { TRIMMABLE_PADDING_REGEX } from '../constants.mjs';
/**
diff --git a/packages/core/src/generators/llms-txt/README.md b/packages/react/src/llms-txt/README.md
similarity index 100%
rename from packages/core/src/generators/llms-txt/README.md
rename to packages/react/src/llms-txt/README.md
diff --git a/packages/core/src/generators/llms-txt/generate.mjs b/packages/react/src/llms-txt/generate.mjs
similarity index 84%
rename from packages/core/src/generators/llms-txt/generate.mjs
rename to packages/react/src/llms-txt/generate.mjs
index 0610b73c..730cbcdc 100644
--- a/packages/core/src/generators/llms-txt/generate.mjs
+++ b/packages/react/src/llms-txt/generate.mjs
@@ -3,9 +3,10 @@
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { writeFile } from '@node-core/doc-kit/utils/file.mjs';
+
import { buildApiDocLink } from './utils/buildApiDocLink.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { writeFile } from '../../utils/file.mjs';
/**
* Generates a llms.txt file
diff --git a/packages/core/src/generators/llms-txt/index.mjs b/packages/react/src/llms-txt/index.mjs
similarity index 100%
rename from packages/core/src/generators/llms-txt/index.mjs
rename to packages/react/src/llms-txt/index.mjs
diff --git a/packages/core/src/generators/llms-txt/template.txt b/packages/react/src/llms-txt/template.txt
similarity index 100%
rename from packages/core/src/generators/llms-txt/template.txt
rename to packages/react/src/llms-txt/template.txt
diff --git a/packages/core/src/generators/llms-txt/types.d.ts b/packages/react/src/llms-txt/types.d.ts
similarity index 66%
rename from packages/core/src/generators/llms-txt/types.d.ts
rename to packages/react/src/llms-txt/types.d.ts
index 85c720ed..d84cf4e5 100644
--- a/packages/core/src/generators/llms-txt/types.d.ts
+++ b/packages/react/src/llms-txt/types.d.ts
@@ -1,4 +1,4 @@
-import { MetadataEntry } from '../metadata/types';
+import { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types';
export type Generator = GeneratorMetadata<
{
diff --git a/packages/core/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs b/packages/react/src/llms-txt/utils/__tests__/buildApiDocLink.test.mjs
similarity index 100%
rename from packages/core/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs
rename to packages/react/src/llms-txt/utils/__tests__/buildApiDocLink.test.mjs
diff --git a/packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs b/packages/react/src/llms-txt/utils/buildApiDocLink.mjs
similarity index 70%
rename from packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs
rename to packages/react/src/llms-txt/utils/buildApiDocLink.mjs
index 271249d0..e061d513 100644
--- a/packages/core/src/generators/llms-txt/utils/buildApiDocLink.mjs
+++ b/packages/react/src/llms-txt/utils/buildApiDocLink.mjs
@@ -1,12 +1,12 @@
-import { populate } from '../../../utils/configuration/templates.mjs';
-import { transformNodeToString } from '../../../utils/unist.mjs';
+import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+import { transformNodeToString } from '@node-core/doc-kit/utils/unist.mjs';
/**
* Retrieves the description of a given API doc entry. It first checks whether
* the entry has a llm_description property. If not, it extracts the first
* paragraph from the entry's content.
*
- * @param {import('../../metadata/types').MetadataEntry} entry
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry
* @returns {string}
*/
export const getEntryDescription = entry => {
@@ -32,8 +32,8 @@ export const getEntryDescription = entry => {
/**
* Builds a markdown link for an API doc entry
*
- * @param {import('../../metadata/types').MetadataEntry} entry
- * @param {import('../../../utils/configuration/types').Configuration['llms-txt']}
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry
+ * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration['llms-txt']}
* @returns {string}
*/
export const buildApiDocLink = (entry, config) => {
diff --git a/packages/core/src/generators/orama-db/README.md b/packages/react/src/orama-db/README.md
similarity index 100%
rename from packages/core/src/generators/orama-db/README.md
rename to packages/react/src/orama-db/README.md
diff --git a/packages/core/src/generators/orama-db/constants.mjs b/packages/react/src/orama-db/constants.mjs
similarity index 100%
rename from packages/core/src/generators/orama-db/constants.mjs
rename to packages/react/src/orama-db/constants.mjs
diff --git a/packages/core/src/generators/orama-db/generate.mjs b/packages/react/src/orama-db/generate.mjs
similarity index 83%
rename from packages/core/src/generators/orama-db/generate.mjs
rename to packages/react/src/orama-db/generate.mjs
index e8ec639d..a7f1b663 100644
--- a/packages/core/src/generators/orama-db/generate.mjs
+++ b/packages/react/src/orama-db/generate.mjs
@@ -2,14 +2,14 @@
import { join } from 'node:path';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { writeFile } from '@node-core/doc-kit/utils/file.mjs';
+import { groupNodesByModule } from '@node-core/doc-kit/utils/generators.mjs';
+import { transformNodeToString } from '@node-core/doc-kit/utils/unist.mjs';
import { create, save, insertMultiple } from '@orama/orama';
import { SCHEMA } from './constants.mjs';
import { buildHierarchicalTitle } from './utils/title.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { writeFile } from '../../utils/file.mjs';
-import { groupNodesByModule } from '../../utils/generators.mjs';
-import { transformNodeToString } from '../../utils/unist.mjs';
/**
* Generates the Orama database.
diff --git a/packages/core/src/generators/orama-db/index.mjs b/packages/react/src/orama-db/index.mjs
similarity index 100%
rename from packages/core/src/generators/orama-db/index.mjs
rename to packages/react/src/orama-db/index.mjs
diff --git a/packages/core/src/generators/orama-db/types.d.ts b/packages/react/src/orama-db/types.d.ts
similarity index 87%
rename from packages/core/src/generators/orama-db/types.d.ts
rename to packages/react/src/orama-db/types.d.ts
index 8c8c14db..6f6fbca7 100644
--- a/packages/core/src/generators/orama-db/types.d.ts
+++ b/packages/react/src/orama-db/types.d.ts
@@ -1,5 +1,5 @@
import type { Orama, RawData } from '@orama/orama';
-import type { MetadataEntry } from '../metadata/types';
+import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types';
/**
* Schema for the Orama database entry
diff --git a/packages/core/src/generators/orama-db/utils/__tests__/title.test.mjs b/packages/react/src/orama-db/utils/__tests__/title.test.mjs
similarity index 100%
rename from packages/core/src/generators/orama-db/utils/__tests__/title.test.mjs
rename to packages/react/src/orama-db/utils/__tests__/title.test.mjs
diff --git a/packages/core/src/generators/orama-db/utils/title.mjs b/packages/react/src/orama-db/utils/title.mjs
similarity index 100%
rename from packages/core/src/generators/orama-db/utils/title.mjs
rename to packages/react/src/orama-db/utils/title.mjs
diff --git a/packages/core/src/generators/sitemap/README.md b/packages/react/src/sitemap/README.md
similarity index 100%
rename from packages/core/src/generators/sitemap/README.md
rename to packages/react/src/sitemap/README.md
diff --git a/packages/core/src/generators/sitemap/entry-template.xml b/packages/react/src/sitemap/entry-template.xml
similarity index 100%
rename from packages/core/src/generators/sitemap/entry-template.xml
rename to packages/react/src/sitemap/entry-template.xml
diff --git a/packages/core/src/generators/sitemap/generate.mjs b/packages/react/src/sitemap/generate.mjs
similarity index 86%
rename from packages/core/src/generators/sitemap/generate.mjs
rename to packages/react/src/sitemap/generate.mjs
index 9ec9786a..808c0ca0 100644
--- a/packages/core/src/generators/sitemap/generate.mjs
+++ b/packages/react/src/sitemap/generate.mjs
@@ -3,10 +3,11 @@
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
+import getConfig from '@node-core/doc-kit/utils/configuration/index.mjs';
+import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+import { writeFile } from '@node-core/doc-kit/utils/file.mjs';
+
import { createPageSitemapEntry } from './utils/createPageSitemapEntry.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { populate } from '../../utils/configuration/templates.mjs';
-import { writeFile } from '../../utils/file.mjs';
/**
* Generates a sitemap.xml file
diff --git a/packages/core/src/generators/sitemap/index.mjs b/packages/react/src/sitemap/index.mjs
similarity index 100%
rename from packages/core/src/generators/sitemap/index.mjs
rename to packages/react/src/sitemap/index.mjs
diff --git a/packages/core/src/generators/sitemap/template.xml b/packages/react/src/sitemap/template.xml
similarity index 100%
rename from packages/core/src/generators/sitemap/template.xml
rename to packages/react/src/sitemap/template.xml
diff --git a/packages/core/src/generators/sitemap/types.d.ts b/packages/react/src/sitemap/types.d.ts
similarity index 81%
rename from packages/core/src/generators/sitemap/types.d.ts
rename to packages/react/src/sitemap/types.d.ts
index abad2fd1..569fec49 100644
--- a/packages/core/src/generators/sitemap/types.d.ts
+++ b/packages/react/src/sitemap/types.d.ts
@@ -1,4 +1,4 @@
-import type { MetadataEntry } from '../metadata/types';
+import type { MetadataEntry } from '@node-core/doc-kit/generators/metadata/types';
export interface SitemapEntry {
loc: string;
diff --git a/packages/react/src/sitemap/utils/createPageSitemapEntry.mjs b/packages/react/src/sitemap/utils/createPageSitemapEntry.mjs
new file mode 100644
index 00000000..eabfa69b
--- /dev/null
+++ b/packages/react/src/sitemap/utils/createPageSitemapEntry.mjs
@@ -0,0 +1,19 @@
+import { populate } from '@node-core/doc-kit/utils/configuration/templates.mjs';
+
+/**
+ * Builds an API doc sitemap url.
+ *
+ * @param {import('@node-core/doc-kit/generators/metadata/types').MetadataEntry} entry
+ * @param {import('@node-core/doc-kit/utils/configuration/types').Configuration['sitemap']} config
+ * @param {string} lastmod - Last-modified date as `YYYY-MM-DD`
+ * @returns {import('../types').SitemapEntry}
+ */
+export const createPageSitemapEntry = (entry, config, lastmod) => ({
+ loc: populate(config.pageURL, {
+ ...config,
+ path: entry.path,
+ }),
+ lastmod,
+ changefreq: 'weekly',
+ priority: '0.8',
+});
diff --git a/scripts/build-docs-content.mjs b/scripts/build-docs-content.mjs
index 07442da1..836a5e0c 100644
--- a/scripts/build-docs-content.mjs
+++ b/scripts/build-docs-content.mjs
@@ -6,11 +6,11 @@
// www/pages/*.md authored narrative pages, copied verbatim
// docs/*.md the existing reference docs
// packages/core/src/generators/*/README.md
-// per-generator config reference, written to
+// packages/*/src/*/README.md per-generator config reference, written to
// `generators/.md`
//
// `www/content/` is a build artifact and is gitignored. Run this before
-// invoking the `web` generator against it.
+// invoking the `html` generator against it.
import { glob, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { basename, dirname, join } from 'node:path';
@@ -25,6 +25,10 @@ const SOURCES = [
pattern: 'packages/core/src/generators/*/README.md',
rename: file => `generators/${basename(dirname(file))}.md`,
},
+ {
+ pattern: 'packages/*/src/*/README.md',
+ rename: file => `generators/${basename(dirname(file))}.md`,
+ },
];
/**
diff --git a/scripts/vercel-build.sh b/scripts/vercel-build.sh
index a9f5fd9a..5940b71f 100755
--- a/scripts/vercel-build.sh
+++ b/scripts/vercel-build.sh
@@ -9,7 +9,7 @@ node packages/core/bin/cli.mjs generate \
-t orama-db \
-t legacy-json \
-t llms-txt \
- -t web \
+ -t html \
-i "./node/doc/api/*.md" \
--ignore "./node/doc/api/quic.md" \
-o "./out" \
diff --git a/www/doc-kit.config.mjs b/www/doc-kit.config.mjs
index 017c440a..1dfb8cd6 100644
--- a/www/doc-kit.config.mjs
+++ b/www/doc-kit.config.mjs
@@ -28,7 +28,7 @@ const DESCRIPTION =
/** @type {import('../packages/core/src/utils/configuration/types').Configuration} */
export default {
- target: ['orama-db', 'legacy-json', 'web'],
+ target: ['orama-db', 'legacy-json', 'html'],
global: {
// `www/content/` is assembled by `scripts/build-docs-content.mjs`.
@@ -55,7 +55,7 @@ export default {
generateIndexPage: false,
},
- web: {
+ html: {
project: 'doc-kit',
title: '{project} documentation',
diff --git a/www/pages/getting-started.md b/www/pages/getting-started.md
index a687ebca..8c8e3b64 100644
--- a/www/pages/getting-started.md
+++ b/www/pages/getting-started.md
@@ -48,12 +48,12 @@ that's fully customizable via [a configuration file][].
## Render the modern site
-The `web` target produces the server-rendered, client-hydrated site that
+The `html` target produces the server-rendered, client-hydrated site that
[nodejs.org](https://nodejs.org) uses — and that this site is built with:
```bash
npx doc-kit generate \
- -t web \
+ -t html \
-i "docs/*.md" \
-o out
```
@@ -61,12 +61,12 @@ npx doc-kit generate \
Pair it with `orama-db` to add search:
```bash
-npx doc-kit generate -t web -t orama-db -i "docs/*.md" -o out
+npx doc-kit generate -t html -t orama-db -i "docs/*.md" -o out
```
## Preview it locally
-The `web` output uses import maps and client-side hydration, so it must be
+The `html` output uses import maps and client-side hydration, so it must be
served over HTTP — opening the files directly with `file://` will not work. Any
static server will do the trick; for example:
@@ -78,9 +78,9 @@ Then open the printed URL (usually ). The
`legacy-html-all` output from earlier has no such requirement — `out/all.html`
opens straight from disk.
-## Customize the `web` generator output
+## Customize the `html` generator output
-The power of the `web` generator comes from its customization hooks. Let's walk
+The power of the `html` generator comes from its customization hooks. Let's walk
through a couple quick changes.
Create a `doc-kit.config.mjs` file at the root of the project.
@@ -90,7 +90,7 @@ import { join } from 'node:path';
/** @type {import('@node-core/doc-kit/src/utils/configuration/types').Configuration} */
export default {
- web: {
+ html: {
project: 'My Project', // Project name used in page titles and the version selector
remoteConfigUrl: '', // Suppress the Node.js default that sets the top banner based on Node.js news.
head: {
@@ -130,7 +130,7 @@ experience, preserving core functionality.
- Explore [Configuration](./configuration.html) — consider moving your `-t`
target flags into a `doc-kit.config.mjs` file.
-- [Further customize the `web` generator](./generators/web.html) — give it a
+- [Further customize the `html` generator](./generators/html.html) — give it a
custom sidenav or footer.
- [Read the full input specification](./specification.html) — the full Markdown
contract.
diff --git a/www/pages/index.md b/www/pages/index.md
index 9a193e54..7ee686d5 100644
--- a/www/pages/index.md
+++ b/www/pages/index.md
@@ -4,7 +4,7 @@
documentation. It's the documentation toolchain behind the Node.js API
reference, found at https://nodejs.org/docs/latest/api/. This site is built by
`doc-kit`, from its own repository. The pages you are reading were produced by
-the `web` generator.
+the `html` generator.
> 📣 `doc-kit` is in beta. We'd like feedback within the
> [issue log](https://github.com/nodejs/doc-kit/issues) or by visiting the
@@ -24,7 +24,7 @@ Raw Markdown Files
│
[metadata] extract structured API metadata
│
- ├─► [jsx-ast] ─► [web] server-rendered site
+ ├─► [jsx-ast] ─► [html] server-rendered site
├─► [legacy-html] ─► …-all classic HTML
├─► [legacy-json] ─► …-all JSON
├─► [json-simple] simplified JSON
@@ -39,7 +39,7 @@ Only some of these are things you ask for by name. `ast`, `metadata`, and
them, and they are not valid `-t` targets. Everything in the fan-out below
`metadata` is a target you can pass to `-t`, and passing several at once reuses
the one shared parse rather than repeating it. The full list is in the
-[generators reference](./generators/web.html).
+[generators reference](./generators/html.html).
## The input contract
@@ -65,7 +65,7 @@ See [the specification](./specification.html) for the full input format.
A couple places `doc-kit` is already in use. Feel free to PR yours.
- - `legacy-json`
-- - `web`
-- - `web`
-- - `web`
-- - `web`
+- - `html`
+- - `html`
+- - `html`
+- - `html`