# `html` Generator 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 bundler. The generator is output-only and does not return an in-memory copy of its HTML or CSS. ## 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:** `{}`. - `bundler` {WebBundler} Adapter that renders server entries and writes the client and HTML output. 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 `