# `html` Generator The `html` generator turns the pages' JSX into a complete static site: the server-rendered HTML pages, the client-side JavaScript, CSS, and imported assets, written to `output`. Vite is the default bundler adapter, but projects can supply an adapter for webpack or another bundler. The generator is output-only and does not return an in-memory copy of its HTML or CSS. The site is built in pieces that are each as small as they can be. The bundler builds the component library once and the client assets once. Each page's program is then compiled — JSX to a plain module — and the worker pool imports, renders, templates, minifies and writes the pages one at a time, so memory scales with the largest page rather than with the site. `all.html` is assembled from the module pages' compiled content rather than built again from scratch. ## Configuring - `output` {string} The directory where HTML and bundled client output are written. Required. - `templatePath` {string} Path to the HTML template file. **Default:** `'template.html'`. - `project` {string} Project name used in page titles and the version selector. **Default:** inherited from `global.project`. - `title` {string} Title template for HTML pages (supports `{project}`, `{version}`). **Default:** `'{project} v{version} Documentation'`. - `useAbsoluteURLs` {boolean} When `true`, all internal links use absolute URLs based on `baseURL`. **Default:** `false`. - `editURL` {string} URL template for "edit this page" links. **Default:** none — the "edit this page" link is omitted. - `pageURL` {string} URL template for documentation page links. **Default:** `'{baseURL}{path}.html'`. - `remoteConfigUrl` {string} URL fetched client-side at runtime for remote site config (currently used to power the announcement banner). **Default:** none — no runtime fetch, no banner. - `head` {Object} Configurable ``, ``, and raw markup for the document head. See [`head`](#head). - `stylesheets` {Array} Paths to extra stylesheets bundled after the built-in one. See [`stylesheets`](#stylesheets). **Default:** `[]`. - `imports` {Object} Object mapping `#theme/` aliases to component paths for customization. See [Default `imports`](#default-imports). - `virtualImports` {Object} Additional virtual module mappings supplied to the server and client builds. **Default:** `{}`. - `components` {Object} Maps JSX tag names to component imports, enabling JSX-in-MDX. See [`components`](#components). **Default:** `{}`. - `navigation` {Object} Sidebar groups and navigation bar items. See [`navigation`](#navigation). **Default:** `{}`. - `generateAllPage` {boolean} When `true`, writes `all.html`: every module page's content on one page, in sidebar order, assembled from the module pages rather than built again. Chunk pages and the index are left out. **Default:** `true`. - `bundler` {WebBundler} Adapter that bundles the component library and the client assets, and compiles page programs. See [Bundler adapters](#bundler-adapters). **Default:** `createViteBundler()`. ### `head` - `meta` {Array} `` tags. Each entry is an attribute bag, e.g. `{ name: 'description', content: '…' }`. - `links` {Array} `` tags. Each entry is an attribute bag, e.g. `{ rel: 'icon', href: '…' }`. - `html` {Array} Raw HTML strings appended verbatim — an escape hatch for anything not expressible above. The `head` object controls the project-specific markup injected into the document `` (rendered into the template's `${head}` placeholder). Each attribute bag is rendered as a tag: a boolean `true` becomes a valueless attribute (e.g. `crossorigin`), and `false`/`null`/`undefined` attributes are omitted. Using arrays of attribute bags (rather than `name → value` maps) means you can emit repeated tags (e.g. two `preconnect` links) and pick the right attribute (`name` vs `property`) per tag. The default `head` is empty — brand the output by supplying your own tags: ```js // doc-kit.config.mjs export default { html: { head: { meta: [ { name: 'description', content: 'My project documentation' }, { property: 'og:image', content: 'https://example.com/og.png' }, ], links: [ { rel: 'icon', href: 'https://example.com/favicon.ico' }, { rel: 'stylesheet', href: 'https://example.com/fonts.css' }, ], html: [''], }, }, }; ``` > Structural and theme-bound tags are emitted by the template itself rather than > via `head`, including `og:title` (which mirrors the per-page title) and > `og:type`. The UI stylesheet bundles its fonts locally. ### `stylesheets` Each entry is a path to a CSS file, bundled into the site's single stylesheet after the built-in one — so its rules and custom properties win. Relative paths resolve against the working directory; prefer absolute paths (e.g. `join(import.meta.dirname, 'theme.css')`) when the config file can be loaded from elsewhere. The built-in accent palette is a project-neutral grey. Rebrand the output by redefining the nine `--color-brand-*` custom properties, which the UI components use for links, focus rings, and active states: ```css /* theme.css */ :root { --color-brand-100: #edf2eb; --color-brand-200: #c5e5b4; --color-brand-300: #99cc7d; --color-brand-400: #84ba64; --color-brand-500: #5fa04e; --color-brand-600: #417e38; --color-brand-700: #2c682c; --color-brand-800: #2c682c; --color-brand-900: #1a3f1d; } ``` ```js // doc-kit.config.mjs import { join } from 'node:path'; export default { html: { stylesheets: [join(import.meta.dirname, 'theme.css')], }, }; ``` ### `navigation` - `sidebar` {Array} Sidebar groups, each `{ groupName, items }`. Defaults to one `API Documentation` group holding every page. - `navbar` {Array} Navigation bar items, each `{ text, link, target? }`. Defaults to none, which renders no items. The `navigation` object supplies the site's two navigation surfaces. Both keys 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/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.

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

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

The sidebar also renders a version `