{ "type": "module", "source": "doc/api/customization.md", "modules": [ { "textRaw": "Customizing the site", "name": "customizing_the_site", "type": "module", "desc": "

This page walks the customizations most projects make, in the\norder they usually make them. The complete option list lives in the\nhtml generator reference.

\n

All of it goes in the html section of your configuration file:

\n
export default {\n  target: ['html'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n\n  html: {\n    // ... everything on this page\n  },\n};\n
", "modules": [ { "textRaw": "Name and titles", "name": "name_and_titles", "type": "module", "desc": "
html: {\n  project: 'My Project', // Used in page titles and the version selector\n  title: '{project} Documentation', // Browser-tab title template\n  // Suppress the Node.js announcement banner fetched at runtime\n  remoteConfigUrl: '',\n},\n
\n

title supports {project} and {version} placeholders.

", "displayName": "Name and titles" }, { "textRaw": "The ``", "name": "the_``", "type": "module", "desc": "

head controls the markup injected into every page's <head>:

\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: [{ rel: 'icon', href: '/favicon.ico' }],\n    html: [\n      `<style>\n        :root, :root.dark {\n          --color-brand-400: #b8adff;\n          --color-brand-600: #6e5cd9;\n        }\n      </style>`,\n    ],\n  },\n},\n
\n

The <style> override above re-brands the accent color: the UI derives its\npalette from --color-brand-* custom properties, so a few lines of CSS\nrestyle the whole site.

", "displayName": "The ``" }, { "textRaw": "Navigation", "name": "navigation", "type": "module", "desc": "

Without configuration, the sidebar is one group holding every page. The\nnavigation key allows you to customize it:

\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: '`api`', link: '/api' }],\n      },\n    ],\n    navbar: [\n      {\n        text: 'GitHub',\n        link: 'https://github.com/nodejs/doc-kit',\n        target: '_blank',\n      },\n    ],\n  },\n},\n
\n

Sidebar links are page paths without extensions; backticked spans in a\nlabel render as code. Items can nest through their own items array. The\nsidebar also shows a version selector when your configuration provides a\nchangelog.

", "displayName": "Navigation" }, { "textRaw": "Logo and theme components", "name": "logo_and_theme_components", "type": "module", "desc": "

Every piece of the page surrounding your content is a component you can replace. Override any\n#theme/* alias with a path to your own:

\n
html: {\n  imports: {\n    '#theme/Logo': './src/MyLogo.jsx',\n    '#theme/Footer': './src/MyFooter.jsx',\n  },\n},\n
\n
export default () => (\n  <svg height=\"30\" width=\"30\" viewBox=\"0 0 10 10\">\n    <circle cx=\"5\" cy=\"5\" r=\"5\" fill=\"var(--color-brand-400)\" />\n  </svg>\n);\n
\n

Available slots: #theme/Logo, #theme/Navigation, #theme/Sidebar,\n#theme/Metabar, #theme/Footer (renders nothing by default), and\n#theme/Layout (the outermost wrapper). Custom components can import\nwhatever build-time data they need — project name, version list, page index\n— from the #theme/config virtual module; see the\nhtml reference for its exports.

", "displayName": "Logo and theme components" }, { "textRaw": "Custom components and MDX", "name": "custom_components_and_mdx", "type": "module", "desc": "

Register your own JSX components and use them directly in content:

\n
html: {\n  components: {\n    Hero: '#theme/Hero',\n  },\n  imports: {\n    '#theme/Hero': './src/components/Hero.jsx',\n  },\n},\n
\n
---\ntitle: Welcome\n---\n\n# Welcome\n\n<Hero title=\"My Project\" />\n
\n

Author component-bearing pages as .mdx files (or set mdx: true in a\npage's frontmatter). Regular .md files treat < and { literally, which\nis what API documentation wants; MDX pages get real JSX and skip API-doc\nsignature parsing while keeping headings, TOC, and sidebar behavior.

", "displayName": "Custom components and MDX" }, { "textRaw": "The bundler", "name": "the_bundler", "type": "module", "desc": "

Vite builds the site by default, and accepts your plugins and options:

\n
import { createViteBundler } from '@doc-kit/generator-react/html/bundlers/vite';\n\nexport default {\n  html: {\n    bundler: createViteBundler({\n      plugins: [myVitePlugin()],\n    }),\n  },\n};\n
\n

A different bundler entirely (webpack, Rspack, …) can be supplied as a small\nadapter object — see Bundler adapters in the\nreference.

", "displayName": "The bundler" } ], "displayName": "Customizing the site" } ] }