Skip to content

README.md

Latest commit

 

History

History
98 lines (76 loc) · 6.23 KB

README.md

File metadata and controls

98 lines (76 loc) · 6.23 KB

web Generator

The web generator transforms JSX AST entries into complete web bundles, producing server-side rendered HTML pages, client-side JavaScript with code splitting, and bundled CSS styles.

Configuring

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

Alias Default Description
#theme/Logo @node-core/ui-components/Common/NodejsLogo Logo rendered inside the navigation bar
#theme/Navigation Built-in NavBar component Top navigation bar
#theme/Sidebar Built-in SideBar component Sidebar with version selector and page links
#theme/Layout Built-in Layout component Outermost wrapper around the full page

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

// doc-kit.config.mjs
export default {
  web: {
    imports: {
      '#theme/Logo': './src/MyLogo.jsx',
      '#theme/Sidebar': './src/MySidebar.jsx',
    },
  },
};

#theme/config virtual module

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.

import { project, repository, editURL } from '#theme/config';

Available exports

All scalar (non-object) configuration values are automatically exported. The defaults include:

Export Type Description
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)
editURL string Partially populated "edit this page" URL template (only {path} remains)
pages Array<[string, string]> Sorted [name, path] tuples for sidebar navigation
languageDisplayNameMap Map<string, string> Shiki language alias → display name map for code blocks

Usage in custom components

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

// my-custom-sidebar.jsx
import { pages, versions, version } from '#theme/config';

export default ({ metadata }) => (
  <nav>
    <p>Current: {version}</p>
    <ul>
      {pages.map(([name, path]) => (
        <li key={path}>
          <a href={`${path}.html`}>{name}</a>
        </li>
      ))}
    </ul>
  </nav>
);

Layout props

The Layout component receives the following props:

Prop Type Description
metadata object Serialized page metadata — all YAML frontmatter properties plus addedIn, basename, path, and any custom user-defined fields
headings Array Pre-computed table of contents heading entries
readingTime string Estimated reading time (e.g. '5 min read')
children ComponentChildren Processed page content

Custom Layout components can use any combination of these props alongside #theme/config imports.