diff --git a/package-lock.json b/package-lock.json index db2d2501..3f72098b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@node-core/doc-kit", - "version": "1.3.1", + "version": "1.3.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@node-core/doc-kit", - "version": "1.3.1", + "version": "1.3.2", "dependencies": { "@actions/core": "^3.0.0", "@heroicons/react": "^2.2.0", diff --git a/package.json b/package.json index e1e4a9ed..885c7512 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@node-core/doc-kit", "type": "module", - "version": "1.3.1", + "version": "1.3.2", "repository": { "type": "git", "url": "git+https://github.com/nodejs/doc-kit.git" diff --git a/src/generators/jsx-ast/utils/buildContent.mjs b/src/generators/jsx-ast/utils/buildContent.mjs index 911771bb..12f54825 100644 --- a/src/generators/jsx-ast/utils/buildContent.mjs +++ b/src/generators/jsx-ast/utils/buildContent.mjs @@ -9,7 +9,7 @@ import { SKIP, visit } from 'unist-util-visit'; import { createJSXElement } from './ast.mjs'; import { extractHeadings, extractTextContent } from './buildBarProps.mjs'; import { enforceArray } from '../../../utils/array.mjs'; -import { extractPrimitives } from '../../../utils/misc.mjs'; +import { omitKeys } from '../../../utils/misc.mjs'; import { JSX_IMPORTS } from '../../web/constants.mjs'; import { STABILITY_LEVELS, @@ -296,7 +296,13 @@ export const createDocumentLayout = (entries, metadata) => * @returns {Promise} */ const buildContent = async (metadataEntries, head) => { - const metadata = extractPrimitives(head); + // The metadata is the heading without the node children + const metadata = omitKeys(head, [ + 'content', + 'heading', + 'stability', + 'changes', + ]); // Create root document AST with all layout components and processed content const root = createDocumentLayout(metadataEntries, metadata); diff --git a/src/generators/web/README.md b/src/generators/web/README.md index 0941b8a7..ed6246aa 100644 --- a/src/generators/web/README.md +++ b/src/generators/web/README.md @@ -6,13 +6,16 @@ The `web` generator transforms JSX AST entries into complete web bundles, produc The `web` generator accepts the following configuration options: -| Name | Type | Default | Description | -| -------------- | -------- | --------------------------------------------- | --------------------------------------------------------------------- | -| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written | -| `templatePath` | `string` | `'template.html'` | Path to the HTML template file | -| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links | -| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links | -| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization | +| Name | Type | Default | Description | +| ---------------- | -------- | --------------------------------------------- | --------------------------------------------------------------------- | +| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written | +| `templatePath` | `string` | `'template.html'` | Path to the HTML template file | +| `project` | `string` | `'Node.js'` | Project name used in page titles and the version selector | +| `title` | `string` | `'{project} v{version} Documentation'` | Title template for HTML pages (supports `{project}`, `{version}`) | +| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links | +| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links | +| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization | +| `virtualImports` | `object` | `{}` | Additional virtual module mappings merged into the build | #### Default `imports` @@ -42,14 +45,16 @@ export default { 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. ```js -import { title, repository, editURL } from '#theme/config'; +import { project, repository, editURL } from '#theme/config'; ``` #### Available exports +All scalar (non-object) configuration values are automatically exported. The defaults include: + | Export | Type | Description | | ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------- | -| `title` | `string` | Site title (e.g. `'Node.js'`) | +| `project` | `string` | Project name (e.g. `'Node.js'`) | | `repository` | `string` | GitHub repository in `owner/repo` format | | `version` | `string` | Current version label (e.g. `'v22.x'`) | | `versions` | `Array<{ url, label, major }>` | Pre-computed version entries with labels and URL templates (only `{path}` remains for per-page use) | diff --git a/src/generators/web/index.mjs b/src/generators/web/index.mjs index 6d783fbd..e41b76aa 100644 --- a/src/generators/web/index.mjs +++ b/src/generators/web/index.mjs @@ -29,7 +29,8 @@ export default createLazyGenerator({ defaultConfiguration: { templatePath: join(import.meta.dirname, 'template.html'), - title: 'Node.js', + project: 'Node.js', + title: '{project} v{version} Documentation', editURL: `${GITHUB_EDIT_URL}/doc/api{path}.md`, pageURL: '{baseURL}/latest-{version}/api{path}.html', imports: { @@ -40,5 +41,6 @@ export default createLazyGenerator({ '#theme/Footer': join(import.meta.dirname, './ui/components/NoOp'), '#theme/Layout': join(import.meta.dirname, './ui/components/Layout'), }, + virtualImports: {}, }, }); diff --git a/src/generators/web/template.html b/src/generators/web/template.html index 71d0de0e..eed99d1b 100644 --- a/src/generators/web/template.html +++ b/src/generators/web/template.html @@ -5,10 +5,10 @@ - {{title}} + {title} - - + + @@ -20,12 +20,12 @@ - - + + -
{{dehydrated}}
- +
{dehydrated}
+ diff --git a/src/generators/web/types.d.ts b/src/generators/web/types.d.ts index 5feed60e..15229094 100644 --- a/src/generators/web/types.d.ts +++ b/src/generators/web/types.d.ts @@ -1,10 +1,13 @@ import type { JSXContent } from '../jsx-ast/utils/buildContent.mjs'; +export type Configuration = { + templatePath: string; + title: string; + imports: Record; + virtualImports: Record; +}; + export type Generator = GeneratorMetadata< - { - templatePath: string; - title: string; - imports: Record; - }, + Configuration, Generate, AsyncGenerator<{ html: string; css: string }>> >; diff --git a/src/generators/web/ui/components/NavBar.jsx b/src/generators/web/ui/components/NavBar.jsx index a2315a4c..15fa85dd 100644 --- a/src/generators/web/ui/components/NavBar.jsx +++ b/src/generators/web/ui/components/NavBar.jsx @@ -6,7 +6,7 @@ import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub'; import SearchBox from './SearchBox'; import { useTheme } from '../hooks/useTheme.mjs'; -import { title, repository } from '#theme/config'; +import { repository } from '#theme/config'; import Logo from '#theme/Logo'; /** @@ -28,7 +28,7 @@ export default ({ metadata }) => { /> diff --git a/src/generators/web/ui/components/SearchBox/index.jsx b/src/generators/web/ui/components/SearchBox/index.jsx index d89c1d4c..d18798c3 100644 --- a/src/generators/web/ui/components/SearchBox/index.jsx +++ b/src/generators/web/ui/components/SearchBox/index.jsx @@ -8,6 +8,7 @@ import SearchResults from '@node-core/ui-components/Common/Search/Results'; import SearchHit from '@node-core/ui-components/Common/Search/Results/Hit'; import styles from './index.module.css'; +import { relative } from '../../../../../utils/url.mjs'; import useOrama from '../../hooks/useOrama.mjs'; const SearchBox = ({ pathname }) => { @@ -18,7 +19,14 @@ const SearchBox = ({ pathname }) => {
} + onHit={hit => ( + + )} />
diff --git a/src/generators/web/ui/components/SideBar/index.jsx b/src/generators/web/ui/components/SideBar/index.jsx index d2965d17..15d3010b 100644 --- a/src/generators/web/ui/components/SideBar/index.jsx +++ b/src/generators/web/ui/components/SideBar/index.jsx @@ -4,7 +4,7 @@ import SideBar from '@node-core/ui-components/Containers/Sidebar'; import styles from './index.module.css'; import { relative } from '../../../../../utils/url.mjs'; -import { title, version, versions, pages } from '#theme/config'; +import { project, version, versions, pages } from '#theme/config'; /** * Extracts the major version number from a version string. @@ -54,7 +54,7 @@ export default ({ metadata }) => { >