Krate Docs

#Customizing the Docs Site

Theme and extend the docs plugin.

The docs plugin turns a src/content/docs/ directory into a full documentation site. This guide walks through the moving parts.

#Enable the plugin

import { defineConfig, docs } from '@krate/core';
import { baseDocsTheme } from '@krate/base-docs-theme';

export default defineConfig({
  plugins: [
    docs({
      contentDir: "src/content/docs",
      title: "My Docs",
      theme: baseDocsTheme(),
      search: { enabled: true, engine: "pagefind" }, // recommended; "docfind" | "json"
      links: [{ icon: "lucide:github", url: "https://github.com/me/project" }],
    }),
  ],
});
Option Description
contentDir Markdown/MDX docs directory (default src/content/docs)
title Title shown in the docs navbar
layout Path to your layout component
theme Alias for layout (path, installed npm package, or factory - see Theming)
sidebar Custom sidebar override
links Social links rendered in the navbar
search Search bar options (see Search)

#What the plugin generates

For every markdown page, the plugin generates a TSX page into .krate/gen/docs/ that renders your layout component with a single typed props object (DocsLayoutProps from @krate/plugin) carrying:

  • The sidebar tree (from the directory structure + frontmatter order)
  • The table of contents (from headings)
  • Breadcrumbs
  • Prev/Next navigation links
  • Search hints (search: { placeholder, hotkey }) for the theme's own DocsSearch component

The plugin does not inject any chrome itself: the theme (layout component) owns the entire page shell - its JSX is the only markup around the rendered content. The generated page passes render props only, so a theme can lay out the sidebar, breadcrumbs, search, and footer however it likes.

It also writes docs/data/sidebar.json and docs/data/search-index.json plus the search assets (Pagefind bundle, or docfind WASM) under docs/search/.

#File conventions

src/content/docs/
  index.md               -> /docs/
  getting-started.md     -> /docs/getting-started/
  guides/
    index.md             -> /docs/guides/
    advanced.md          -> /docs/guides/advanced/

Sidebar sections come from directories; page order within a directory comes from the frontmatter order field. Each directory's index.md becomes the section landing page.

#The layout component

The layout is a normal Krate TSX component receiving a single DocsLayoutProps object (pageTitle, siteTitle, sidebarItems, tocItems, breadcrumbs, prev/next, socialLinks, currentPath, routeBase, tag/category links, and optional options). It renders {children} for the content and owns all surrounding chrome.

A page's # Heading is part of children, so a layout cannot put the frontmatter description below the title by itself. A theme can opt in with titleSlot: true in the descriptor it returns from defineDocsTheme. The docs plugin then removes the leading <h1> from children and passes it as titleHTML; render it, then the description, then {children}. Themes without the flag keep the heading in children. Both built-in themes use it.

#Theming

The default @krate/base-docs-theme package ships the stock shell - navbar, sidebar, table of contents, breadcrumbs, prev/next, and light/dark mode - as a single composable component. Use its baseDocsTheme() factory:

import { baseDocsTheme } from '@krate/base-docs-theme';

docs({
  contentDir: "src/content/docs",
  theme: baseDocsTheme(),
});

#Zero-JS theme

@krate/simple-docs-theme is a lighter shell whose chrome ships no client runtime. The color-theme switch and mobile drawer compile to CSS signals; the sidebar and mobile table of contents use native <details> disclosures and links. It has no client-side search UI, so point searchHref at a search page or leave it out:

import { simpleDocsTheme } from '@krate/simple-docs-theme';

docs({
  contentDir: "src/content/docs",
  theme: simpleDocsTheme({ searchHref: "/search/" }),
  search: { enabled: false },
});

Setting search.enabled: false keeps the docs plugin from emitting its search script; searchHref then links to a search page you own. Style the theme with the --simple-* custom properties (--simple-accent, --simple-bg, --simple-fg, --simple-border, and so on).

You can swap the whole docs shell with the theme option instead of layout. A theme is one of:

  • A path ("./src/components/my-layout.tsx" or an absolute path) - a plain layout component, exactly like layout. Setting both layout and a theme that points elsewhere is an error.
  • An installed npm package - a bare specifier like "@krate/base-docs-theme" is emitted as-is, so the theme's own CSS and sub-components flow through the bundler graph. Resolution walks up from the project root through node_modules.
  • A factory descriptor via defineDocsTheme from @krate/plugin:
import { defineDocsTheme } from '@krate/plugin';

export default defineDocsTheme({
  name: "my-docs-theme",
  // layout?: string                     // override component path
  // module: string                      // default: this file (import.meta.url)
  options: { primaryColor: "teal" },     // forwarded as docsProps.options
});

Theme options are forwarded to the component as docsProps.options, so one published theme can be configured per-site without forking it.

The theme's layout component is whatever the module default-exports; pages import it and pass every docs data field in as props. It can render that data itself or hand it to imported sub-components - nothing about the layout is hardcoded by the docs plugin.

#Styling

Docs pages are built exactly like normal pages, so a layout's CSS is imported the normal way and bundled into the site's global stylesheet:

// In your docs layout component:
import "./docs-theme.css";

Docs pages link that global stylesheet automatically - no manual <link> and no special docs-styles.css file. This works for relative CSS imports in the project (./theme.css), from an installed theme package, or for site-wide styles in a page/layout module.

Notes:

  • Search styles come from the theme's .krate-docs-search-* classes - override them from your own imported stylesheet, or replace DocsSearch with your own combobox against window.__krateSearch.
  • Interactive behavior (sidebar, TOC tracking, theme toggle) lives in the theme component itself (@krate/base-docs-theme), not a separate script. @krate/simple-docs-theme takes the opposite approach: its chrome has no runtime, using CSS signals and native disclosures instead.

Use CSS custom properties to retheme: --color-primary, --color-bg, --color-fg, --color-border, --radius, etc.

#Writing docs content

See Markdown & MDX for frontmatter and content features, and Search for tuning search relevance.

Last updated: 2026-11-17

Contributors: Noinkin