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

The html generator turns the pages' JSX into a complete static site: the\nserver-rendered HTML pages, the client-side JavaScript, CSS, and imported\nassets, written to output. Vite is the default bundler adapter, but projects\ncan supply an adapter for webpack or another bundler. The generator is\noutput-only and does not return an in-memory copy of its HTML or CSS.

\n

The site is built in pieces that are each as small as they can be. The bundler\nbuilds the component library once and the client assets once. Each page's\nprogram is then compiled — JSX to a plain module — and the worker pool imports,\nrenders, templates, minifies and writes the pages one at a time, so memory\nscales with the largest page rather than with the site. all.html is assembled\nfrom the module pages' compiled content rather than built again from scratch.

", "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

buildServer receives { entry, virtualImports, outDir, config }. The entry\nis the component library's source: re-exports of every component a page may\nrender, Preact's h and Fragment, and renderToStringAsync. It must be\nbundled into one self-contained module written under outDir (a temporary\ndirectory the generator removes afterwards), since the page programs import it\nfrom wherever they are compiled to.

\n

compile(code, fileName) receives one page program: a module that imports the\nlibrary and exports the page's content and a default function rendering the\npage from its layout props, written in JSX. It must return plain JavaScript. The JSX must compile with the classic\nruntime to calls of the _jsx and _Fragment bindings the program imports\n(these names are exported as JSX_PRAGMA and JSX_PRAGMA_FRAG from the\ngenerator's constants.mjs), so that the page and the library share one Preact.

\n

buildClient receives { entry, virtualImports, config }. The client entry\nis a single program shared by every page. It must be bundled into\nconfig.output and the call must return\n{ scripts, preloads, stylesheets }: paths relative to the output root of the\nmodule scripts to load, the chunks they statically import (rendered as\nmodulepreload hints), and the stylesheets. The generator renders those into\nevery page, resolved against the page's location.

\n

config is the resolved html configuration. The adapter must compile the\ngenerated Preact JSX and CSS imports and resolve the supplied theme aliases and\nvirtual modules. The generated #theme/config module exports server as\ntrue for the server build and false for the client 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  async buildServer({ entry, virtualImports, outDir, config }) {\n    // Materialize or load the in-memory modules, run webpack's Node target\n    // with the entry, write one self-contained module under `outDir`, and\n    // return its `file:` URL.\n  },\n\n  async compile(code, fileName) {\n    // Transform the page's JSX (classic runtime, pragma `_jsx`, fragment\n    // pragma `_Fragment`) and return the resulting module source.\n  },\n\n  async buildClient({ entry, virtualImports, config }) {\n    // Run webpack's browser target into config.output and return\n    // { scripts, preloads, stylesheets } as output-relative paths.\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 output, and SSR dependency bundling. Values supplied for those\nfields are replaced after configuration is merged. User plugins are registered\nafter the generator's virtual-module plugin; other Vite options are preserved.

\n

Vite builds the client entry as a module, not the pages as HTML entries, so\nplugins see and can transform every module of the client and server builds but\nnever the HTML pages. Customize the pages through the\nHTML template instead.

\n

The adapter reads the client asset names from Vite's manifest. A manifest is\nwritten either way; pass build: { manifest: true } (or a file name) to\ncreateViteBundler to keep it in the output for another tool.

\n

The adapter is only ever used on the main thread, so function-valued plugins\nand hooks are supported. Worker threads receive the html configuration with\nits function values removed.

", "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
\n

The built-in components are available without registration. Notably,\n<DocumentationIndex /> renders an index of every documented module with its\nstability badge and description, sourced from the documentationIndex export\nof #theme/config.

", "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> ${assets}\n
\n

The populated page is the final HTML: it is minified when minify is set and\nwritten as is. Put ${assets} in the <head>, or the page loads no script and\nno stylesheet.

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