{ "type": "module", "source": "doc/api/generators-html.md", "modules": [ { "textRaw": "`html` Generator", "name": "`html`_generator", "type": "module", "desc": "

The html generator transforms JSX AST entries into complete web bundles. Its\nbundler adapter builds server-rendered HTML and client-side JavaScript, CSS, and\nimported assets, then writes the complete static site to output. Vite is the\ndefault adapter, but projects can supply an adapter for webpack or another\nbundler. The generator is output-only and does not return an in-memory copy of\nits HTML or CSS.

", "modules": [ { "textRaw": "Configuring", "name": "configuring", "type": "module", "desc": "", "modules": [ { "textRaw": "`head`", "name": "`head`", "type": "module", "desc": "\n

The head object controls the project-specific markup injected into the\ndocument <head> (rendered into the template's ${head} placeholder).

\n

Each attribute bag is rendered as a tag: a boolean true becomes a valueless\nattribute (e.g. crossorigin), and false/null/undefined attributes are\nomitted. Using arrays of attribute bags (rather than name → value maps) means\nyou can emit repeated tags (e.g. two preconnect links) and pick the right\nattribute (name vs property) per tag.

\n

The default head is empty — brand the output by supplying your own tags:

\n
// doc-kit.config.mjs\nexport default {\n  html: {\n    head: {\n      meta: [\n        { name: 'description', content: 'My project documentation' },\n        { property: 'og:image', content: 'https://example.com/og.png' },\n      ],\n      links: [\n        { rel: 'icon', href: 'https://example.com/favicon.ico' },\n        { rel: 'stylesheet', href: 'https://example.com/fonts.css' },\n      ],\n      html: ['<meta name=\"theme-color\" content=\"#000\" />'],\n    },\n  },\n};\n
\n
\n

Structural and theme-bound tags are emitted by the template itself rather than\nvia head, including og:title (which mirrors the per-page title) and\nog:type. The UI stylesheet bundles its fonts locally.

\n
", "displayName": "`head`" }, { "textRaw": "`stylesheets`", "name": "`stylesheets`", "type": "module", "desc": "

Each entry is a path to a CSS file, bundled into the site's single stylesheet\nafter the built-in one — so its rules and custom properties win. Relative paths\nresolve against the working directory; prefer absolute paths (e.g.\njoin(import.meta.dirname, 'theme.css')) when the config file can be loaded\nfrom elsewhere.

\n

The built-in accent palette is a project-neutral grey. Rebrand the output by\nredefining the nine --color-brand-* custom properties, which the UI components\nuse for links, focus rings, and active states:

\n
/* theme.css */\n:root {\n  --color-brand-100: #edf2eb;\n  --color-brand-200: #c5e5b4;\n  --color-brand-300: #99cc7d;\n  --color-brand-400: #84ba64;\n  --color-brand-500: #5fa04e;\n  --color-brand-600: #417e38;\n  --color-brand-700: #2c682c;\n  --color-brand-800: #2c682c;\n  --color-brand-900: #1a3f1d;\n}\n
\n
// doc-kit.config.mjs\nimport { join } from 'node:path';\n\nexport default {\n  html: {\n    stylesheets: [join(import.meta.dirname, 'theme.css')],\n  },\n};\n
", "displayName": "`stylesheets`" }, { "textRaw": "`navigation`", "name": "`navigation`", "type": "module", "desc": "\n

The navigation object supplies the site's two navigation surfaces. Both keys\nare optional; omit either one to keep that component's default.

\n

Sidebar items are { label, link } and may nest through an items array of\ntheir own. A label is plain text, except that backticked spans render as\n<code> ('`fs`'), matching how page headings are rendered. A link is a\npage path without its extension (/fs, /generators/html): it is resolved\nagainst the page being rendered, so it obeys useAbsoluteURLs and highlights\nwhile it is the current page. Links starting with http:// or https:// are\nused as authored.

\n

Navigation bar links are always used as authored, since they typically point\noutside the generated site. Give them a target of '_blank' to open in a new\ntab and mark them with an external-link icon.

\n
// doc-kit.config.mjs\nexport default {\n  html: {\n    navigation: {\n      sidebar: [\n        {\n          groupName: 'Guides',\n          items: [{ label: 'Getting started', link: '/getting-started' }],\n        },\n        {\n          groupName: 'Reference',\n          items: [{ label: '`fs`', link: '/fs' }],\n        },\n      ],\n      navbar: [\n        { text: 'Learn', link: 'https://nodejs.org/en/learn' },\n        { text: 'Download', link: 'https://nodejs.org/en/download' },\n      ],\n    },\n  },\n};\n
\n

The sidebar also renders a version <Select> built from changelog. A site\nconfigured without one has no versions to switch between, so the control is\nomitted rather than rendered empty.

", "displayName": "`navigation`" }, { "textRaw": "Bundler adapters", "name": "bundler_adapters", "type": "module", "desc": "\n

The bundler option accepts a small Doc Kit adapter rather than configuration\nfor a particular build system.

\n

Both render and build receive { entries, virtualImports, config }; build\nalso receives pages. Entry maps use ${api}.jsx keys, rendered server results\nuse api keys, and page maps use output-relative HTML file names. config is\nthe resolved html configuration.

\n

The adapter must compile the generated Preact JSX and CSS imports and resolve\nthe supplied theme aliases and virtual modules. The generated #theme/config\nmodule exports server as true for the server build and false for the\nclient build.

\n

A webpack integration can live entirely in project configuration without\nadding webpack to Doc Kit:

\n
// webpack-bundler.mjs\nexport const createWebpackBundler = webpackOptions => ({\n  getEntryId: api => `virtual:doc-kit/client/${api}.jsx`,\n\n  async render({ entries, virtualImports, config }) {\n    // Materialize or load the in-memory modules, run webpack's server target,\n    // execute each emitted entry, and return Map<api, renderedHtml>.\n  },\n\n  async build({ entries, virtualImports, pages, config }) {\n    // Run webpack's browser target, inject its emitted assets into `pages`,\n    // and write the HTML and assets to config.output.\n  },\n});\n
\n
// doc-kit.config.mjs\nimport { createWebpackBundler } from './webpack-bundler.mjs';\n\nexport default {\n  html: {\n    bundler: createWebpackBundler({\n      // Project-owned webpack configuration.\n    }),\n  },\n};\n
", "displayName": "Bundler adapters" }, { "textRaw": "Vite adapter", "name": "vite_adapter", "type": "module", "desc": "

When bundler is omitted, the generator imports and uses\ncreateViteBundler() automatically. To customize Vite, import the adapter\ndirectly and pass Vite's UserConfig to it:

\n
// doc-kit.config.mjs\nimport { createViteBundler } from '@doc-kit/generator-react/html/bundlers/vite';\nimport myVitePlugin from './my-vite-plugin.mjs';\n\nexport default {\n  html: {\n    bundler: createViteBundler({\n      plugins: [myVitePlugin()],\n      define: {\n        'process.env.ANALYTICS_ID': JSON.stringify('UA-XXXXX'),\n      },\n      resolve: {\n        alias: {\n          '@components': './src/components',\n        },\n      },\n      css: {\n        lightningcss: {\n          targets: {\n            chrome: 100 << 16,\n          },\n        },\n      },\n    }),\n  },\n};\n
\n

The generator owns the fields required to coordinate its builds: config-file\nloading, app type and base, virtual inputs, Preact compatibility aliases and\nautomatic JSX runtime, the Lightning CSS transformer, output/write mode, SSR\nformat and temporary output, and SSR dependency bundling. Values supplied for\nthose fields are replaced after configuration is merged. User plugins are\nregistered after the generator's virtual-module plugin; other Vite options are\npreserved.

\n

Vite manifests are optional. Pass build: { manifest: true } or a manifest file\nname to createViteBundler when another tool needs one. The generated HTML\nalready references the correct hashed scripts, stylesheets, imported assets,\nand module preloads.

\n

Function-valued plugins and hooks are supported because the html generator\nruns on the main thread and does not serialize the bundler to a worker.

", "displayName": "Vite adapter" }, { "textRaw": "Default `imports`", "name": "default_`imports`", "type": "module", "desc": "\n

Override any alias in your config file to swap in a custom component:

\n
// doc-kit.config.mjs\nexport default {\n  html: {\n    imports: {\n      '#theme/Logo': './src/MyLogo.jsx',\n      '#theme/Sidebar': './src/MySidebar.jsx',\n    },\n  },\n};\n
", "displayName": "Default `imports`" } ], "displayName": "Configuring" }, { "textRaw": "`components`", "name": "`components`", "type": "module", "desc": "

components registers custom JSX components so they can be used directly in\ncontent (see JSX-in-MDX below). Each entry maps a JSX tag name to\nan import descriptor ({ name, source, isDefaultExport? }, the same shape as the\nbuilt-in JSX_IMPORTS). A Tag: 'source' string shorthand expands to\n{ name: Tag, source } with a default export. Registered components are merged\nwith the built-ins, and a matching imports alias resolves the source to a\nreal module path:

\n
// doc-kit.config.mjs\nexport default {\n  html: {\n    components: {\n      // Shorthand — equivalent to { name: 'Hero', source: '#theme/Hero' }\n      Hero: '#theme/Hero',\n      // Full descriptor\n      Stats: { name: 'Stats', source: '#theme/Stats' },\n    },\n    imports: {\n      '#theme/Hero': './src/components/Hero.jsx',\n      '#theme/Stats': './src/components/Stats.jsx',\n    },\n  },\n};\n
", "displayName": "`components`" }, { "textRaw": "JSX-in-MDX", "name": "jsx-in-mdx", "type": "module", "desc": "

By default every input file is parsed as Markdown, where bare < and { are\ntreated literally (Node.js core docs use <string>-style type annotations). To\nauthor real JSX — <Hero />, {expression} — use an .mdx file, or set\nmdx: true in a file's --- frontmatter (frontmatter wins, so mdx: false\nopts a .mdx file back out). MDX files are parsed with remark-mdx and skip the\nAPI-doc type/signature parsing; headings, frontmatter, TOC, and sidebar still\nwork. Reference any component registered via components:

\n
---\ntitle: Welcome\n---\n\n# Welcome\n\n<Hero title=\"Node.js\" />\n\nThere are {stats.length} APIs documented.\n
", "displayName": "JSX-in-MDX" }, { "textRaw": "`#theme/config` virtual module", "name": "`#theme/config`_virtual_module", "type": "module", "desc": "

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.

\n
import { project, repository, editURL } from '#theme/config';\n
", "modules": [ { "textRaw": "Available exports", "name": "available_exports", "type": "module", "desc": "", "displayName": "Available exports" }, { "textRaw": "Usage in custom components", "name": "usage_in_custom_components", "type": "module", "desc": "

When overriding a #theme/* component, import only the config values you need:

\n
// my-custom-sidebar.jsx\nimport { pages, versions, version } from '#theme/config';\n\nexport default ({ metadata }) => (\n  <nav>\n    <p>Current: {version}</p>\n    <ul>\n      {pages.map(([name, path]) => (\n        <li key={path}>\n          <a href={`${path}.html`}>{name}</a>\n        </li>\n      ))}\n    </ul>\n  </nav>\n);\n
", "displayName": "Usage in custom components" } ], "displayName": "`#theme/config` virtual module" }, { "textRaw": "Layout props", "name": "layout_props", "type": "module", "desc": "\n

The Layout component receives the props above. Custom Layout components can use\nany combination of them alongside #theme/config imports.

", "displayName": "Layout props" }, { "textRaw": "HTML template", "name": "html_template", "type": "module", "desc": "

The HTML template file (set via templatePath) uses JavaScript template literal syntax (${...} placeholders) and is evaluated at build time with full expression support.

", "modules": [ { "textRaw": "Available template variables", "name": "available_template_variables", "type": "module", "desc": "\n

Since the template supports arbitrary JS expressions, you can use conditionals and method calls:

\n
<title>${title}</title>\n<script type=\"module\" src=\"${entrypoint}\"></script>\n
\n

The configured adapter processes each populated page. It must replace or\nresolve entrypoint, include that page's scripts and stylesheets, and write the\nfinal HTML.

", "displayName": "Available template variables" } ], "displayName": "HTML template" } ], "displayName": "`html` Generator" } ] }