Configuration

Global settings and configuration reference for zudo-doc.

zudo-doc is configured through a small set of files in the src/config/ directory and the root zfb.config.ts.

Site Settings

The main settings file is src/config/settings.ts:

export const settings = {
  colorScheme: "Default Dark",
  colorMode: {
    defaultMode: "dark",
    lightScheme: "Default Light",
    darkScheme: "Default Dark",
    respectPrefersColorScheme: true,
  },
  siteName: "zudo-doc",
  siteDescription: "Documentation base framework...",
  base: "/",
  trailingSlash: true,
  docsDir: "src/content/docs",
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
  mermaid: true,
  noindex: false,
  editUrl: false,
  githubUrl: "https://github.com/zudolab/zudo-doc",
  siteUrl: "https://zudo-doc.takazudomodular.com",
  sitemap: true,
  designTokenPanel: true,
  docMetainfo: true,
  docTags: true,
  frontmatterPreview: {},
  math: true,
  docHistory: true,
  claudeResources: {
    claudeDir: ".claude",
  },
  headerNav: [
    { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },
    { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
    { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
    { label: "Claude", labelKey: "nav.claude", path: "/docs/claude", categoryMatch: "claude" },
  ],
};

colorScheme

The active color scheme name. Must match a key in src/config/color-schemes.ts.

Available built-in schemes: Default Light and Default Dark. You can add custom schemes in src/config/color-schemes.ts.

colorMode

Configures light/dark mode behavior. Set to false to disable color mode switching entirely and use only the scheme specified in colorScheme.

When enabled, accepts a ColorModeConfig object:

colorMode: {
  defaultMode: "light",
  lightScheme: "Default Light",
  darkScheme: "Default Dark",
  respectPrefersColorScheme: true,
},
// or disable color mode switching:
colorMode: false,

base

The base path for deploying to a subdirectory. Set this when your site is served from a subpath rather than the root domain.

Default: "/"

For example, to serve the site at https://example.com/my-docs/:

base: "/my-docs",

All internal links (sidebar, navigation, prev/next, search) are automatically prefixed with the base path. The value flows through to zfb's build pipeline so emitted asset URLs and route paths share the same prefix.

trailingSlash

Controls whether URLs end with a trailing slash. When true, all internal links are generated with a trailing slash (e.g., /docs/guides/ instead of /docs/guides). The build-time URL helpers in @takazudo/zudo-doc/url-normalizer enforce this policy across every emitted route — see Trailing-Slash Policy for how the rule splits between build time and the deployment host.

Default: true (the showcase sets this to true; create-zudo-doc scaffolded projects also default to true)

trailingSlash: true,

When enabled, the dev server automatically redirects URLs without a trailing slash to their trailing-slash version with a 301 redirect (e.g., /docs/guides → /docs/guides/) so navigation behaves the same way locally as on production. Static assets (files with extensions like .js, .css, .png) are excluded from the redirect.

onBrokenMarkdownLinks

Controls how broken internal markdown links are handled during the build. This applies to relative [text](./page.mdx) links resolved by zudo-doc's link resolver plugin.

• "warn" — logs a warning but continues the build

• "error" — throws an error and fails the build

• "ignore" — silently skips broken links without any output

Type: "warn" | "error" | "ignore"

Default: "warn"

onBrokenMarkdownLinks: "error", // fail the build on broken links

docsDir

The directory path (relative to the project root) where English documentation MDX files are stored. zfb's content engine globs this directory, so it can point to any location inside the project.

Default: "src/content/docs"

docsDir: "docs",  // content in ./docs/ at project root

This is similar to Docusaurus' docs.path option — useful when using zudo-doc as a documentation tool for a larger project where docs live at the project root level.

defaultLocale

The BCP 47 code for the default (prefix-less) locale. Used by zfb's i18n router to map the root /docs/... routes.

Type: string

Default: "en"

defaultLocale: "en",

locales

A map of additional locale configurations. Each key is a locale code, and the value is an object with label (display name for the language switcher) and dir (content directory path).

Default: {}

locales: {
  ja: { label: "JA", dir: "src/content/docs-ja" },
  ko: { label: "KO", dir: "src/content/docs-ko" },
},

For each locale entry, zudo-doc automatically:

• Creates a zfb content collection (docs-{code})

• Registers the locale in zfb's i18n routing

• Adds it to the language switcher

defaultLocaleOnlyPrefixes

An array of URL prefixes that exist only in the default locale. Pages under these prefixes are not translated and should have no mirror under any locale prefix. The language switcher omits them when on an affected page.

Type: string[]

Default: []

defaultLocaleOnlyPrefixes: [
  "/docs/claude-md/",
  "/docs/claude-skills/",
],

See Default-locale-only prefixes for the full authoring workflow.

versions

Configures multi-version documentation. When set to an array of VersionConfig objects, zudo-doc creates versioned content collections and adds a version switcher to the sidebar. Each versioned section is accessible at /v/{slug}/docs/. Set to false to disable versioning.

Type: VersionConfig[] | false

Default: false

Each VersionConfig object accepts:

versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    banner: "unmaintained",
  },
],
// or disable versioning:
versions: false,

siteName

The site name displayed in the header and used in page titles. Page titles are formatted as {page title} | {siteName}.

siteDescription

A short description of the site. Used in meta tags for SEO and social sharing.

Default: ""

siteUrl

The full base URL of your site (e.g., "https://example.com"). Required for generating absolute URLs in the sitemap.

Default: ""

metaTags

Fine-grained control over which <meta> tags are emitted. Set individual sub-fields to false to omit a tag entirely.

Type: MetaTagsConfig

metaTags: {
  description: true,
  keywords: false,
  ogImage: "/img/ogp.png",
  ogSiteName: true,
  twitterCard: "summary_large_image",
  twitterSite: "@yourbrand",
},

noindex

When true, adds noindex and nofollow meta tags to all pages. Useful for internal documentation sites that should not be indexed by search engines.

Default: false

See Avoid Robots Indexing for a full explanation of the two complementary behaviors this setting activates (<meta name="robots"> and robots.txt).

mermaid

Enables Mermaid diagram support. When true, fenced code blocks with the mermaid language identifier are rendered as diagrams. When false, mermaid code blocks are displayed as plain code.

Default: true

math

Enables KaTeX math equation rendering. When true, inline math ($...$), block math ($$...$$), and fenced math code blocks are rendered as equations.

Default: true

cjkFriendly

Enables CJK-friendly typography adjustments. When true, applies improved line-breaking and word-wrap behavior for Chinese, Japanese, and Korean text throughout the documentation.

Type: boolean

Default: false

cjkFriendly: true,

editUrl

Base URL for "Edit this page" links. The full URL is constructed as editUrl + contentDir + "/" + entryId. Set to false to disable edit links.

Default: false (disabled)

editUrl: "https://github.com/my-org/my-repo/edit/main/",
// or disable:
editUrl: false,

githubUrl

The repository URL shown as the GitHub link in the site header. When set to a string, a GitHub icon link to that URL appears in the header's right-side items (wherever the github-link component is placed in headerRightItems). Set to false to omit the header GitHub link.

Type: string | false

Default: false (the create-zudo-doc scaffold leaves it off; this showcase sets the repo URL)

githubUrl: "https://github.com/my-org/my-repo",
// or omit the header GitHub link:
githubUrl: false,

sitemap

Enables automatic sitemap.xml generation during build. The sitemap includes all built HTML pages except 404.

Default: true

llmsTxt

Enables automatic llms.txt generation during build. When true, an llms.txt file is generated at the site root listing all documentation pages with their titles and descriptions. This file follows the llms.txt specification and helps AI assistants discover and index your documentation content.

Type: boolean

Default: false

llmsTxt: true,

docMetainfo

Shows metadata (created date, last updated date, author) under the page title. Dates and author are extracted from git history at build time.

Default: true

docTags

Enables tag support for documentation pages. When true, pages can use the tags frontmatter field, and tag index pages are generated at /docs/tags/.

See the Tags guide for a full walkthrough.

Default: true

tagPlacement

Controls where the per-page tag badge row renders on doc pages.

Type: "after-title" | "before-pager"

Default: "after-title"

• "after-title" — the badge row appears directly below the page title, above the main content.

• "before-pager" — the badge row appears at the bottom of the content, immediately above the previous/next pager.

tagPlacement: "before-pager",

Has no effect when docTags is false or when a page carries no tags.

tagGovernance

Enforcement level applied when the tag vocabulary is active. See Tag governance for the full reference.

Type: "off" | "warn" | "strict"

Default: "warn"

tagVocabulary

Whether tag-vocabulary.ts is consulted at runtime (alias resolution, deprecation filtering, grouped footer). Set to false to ignore the file entirely regardless of tagGovernance. See Tag governance for details.

Type: boolean

Default: true

frontmatterPreview

Displays custom frontmatter fields as a compact key/value table directly beneath the page title. Framework-managed keys (title, description, sidebar_position, etc.) are hidden by default so only project-specific metadata is shown. Set to false to disable the block on all pages.

Type: FrontmatterPreviewConfig | false

Default: {} (enabled with built-in ignore list)

The FrontmatterPreviewConfig object accepts:

// Extend the default list:
frontmatterPreview: {
  extraIgnoreKeys: ["reviewed_by", "internal_id"],
},
// Replace the default list entirely:
frontmatterPreview: {
  ignoreKeys: ["title", "description", "sidebar_position"],
},
// Disable:
frontmatterPreview: false,

designTokenPanel

Enables the interactive Design Token Panel. When true, a palette icon appears in the header and users can open a tabbed panel to tweak spacing, font, size, and color tokens in real-time. Changes are persisted in localStorage and can be exported/imported as JSON.

Default: false (set to true to enable)

aiAssistant

Enables the AI assistant chat widget. When true, a chat button appears in the page that opens an AI-powered assistant for answering questions about your documentation. The chat API runs as a Cloudflare Workers SSR endpoint (pages/api/ai-chat.tsx) — requires ANTHROPIC_API_KEY, DOCS_SITE_URL, and a RATE_LIMIT KV namespace configured in wrangler.toml.

Type: boolean

Default: false

aiAssistant: true,

aiChatDemoMode

When true, the POST /api/ai-chat endpoint returns a fixed "disabled on this demo" reply without touching any API key, KV namespace, or rate limiter. Set to false in downstream projects that wire up a real ANTHROPIC_API_KEY to enable live Claude-backed chat.

Type: boolean

Default: true

aiChatAllowedOrigins

Allowed CORS origins for POST /api/ai-chat when aiChatDemoMode is false. Non-matching origins receive no Access-Control-Allow-Origin header, so browsers block the request. An empty array (default) blocks all cross-origin browser requests while still allowing same-origin requests.

Type: string[]

Default: []

aiChatAllowedOrigins: ["https://your-docs-site.example.com"],

aiChatGlobalDailyLimit

Optional global daily request ceiling across all IPs as a cost backstop. false (default) disables the ceiling. When set to a positive integer (e.g. 500), the endpoint returns HTTP 429 once that many requests have been served in the current UTC day. Has no effect in demo mode.

Type: number | false

Default: false

aiChatGlobalDailyLimit: 500,

sidebarToggle

Enables the sidebar collapse toggle. When true, a button in the sidebar header allows users to collapse the sidebar entirely, giving more horizontal space for content. The collapsed state is persisted in localStorage.

Type: boolean

Default: false

sidebarToggle: true,

sidebarResizer

Enables sidebar width resizing. When true, a drag handle appears at the sidebar's right edge, allowing users to drag and resize the sidebar width. The resized width is persisted in localStorage.

Type: boolean

Default: false

sidebarResizer: true,

docHistory

Enables per-document git revision history viewer. When true, each doc page shows a History button that opens a side panel with the document's git commit history and a line-by-line diff viewer for comparing revisions.

In dev mode, history is served by the standalone @takazudo/zudo-doc-history-server package running on port 4322. In production, a CLI generator creates static JSON files during CI. See the Doc History Server reference for details on the server and CLI.

Default: false (set to true to enable)

bodyFootUtilArea

Controls which utility items appear in the bottom-of-body action area on every doc page. Set to false to hide the area entirely.

Type: BodyFootUtilAreaConfig | false

Default: false

bodyFootUtilArea: {
  docHistory: true,
  viewSourceLink: true,
},
// or hide entirely:
bodyFootUtilArea: false,

tocMinDepth

Minimum heading depth included in the table of contents (restriction-only: 2–4, default 2). Raise to 3 or 4 to hide shallower headings from the TOC. Cannot go below 2 (h1 is always the page title) or above tocMaxDepth.

Type: number

Default: 2

tocMinDepth: 3, // hide h2 headings from the TOC

tocMaxDepth

Maximum heading depth included in the table of contents (restriction-only: 2–4, default 4). Lower to 2 or 3 to hide deeper headings from the TOC. Cannot exceed 4 or go below tocMinDepth.

Type: number

Default: 4

tocMaxDepth: 3, // hide h4 headings from the TOC

headingIdStrategy

Controls how heading anchor IDs are generated.

• "flat" (zfb default) — github-slugger slugs with one dedup counter shared across h2–h6 (e.g., overview, overview-1).

• "hierarchical" — each heading's slug is prefixed with its ancestor chain (e.g., ## Foo / ### Bar → foo, foo-bar), deduped on the full path so anchors collide far less often.

Switching from "flat" to "hierarchical" is anchor-breaking for existing deep links to nested headings.

Type: "flat" | "hierarchical"

Default: "hierarchical"

headingIdStrategy: "flat",

htmlPreview

Global configuration for the <HtmlPreview> component. When set, the provided head, css, and js are injected into every <HtmlPreview> iframe on the site — useful for loading shared fonts, a design system stylesheet, or utility scripts without repeating them on each component demo.

Set to undefined (the default) to disable global injection.

Type: HtmlPreviewConfig | undefined

Default: undefined

The HtmlPreviewConfig object accepts:

htmlPreview: {
  head: `<link rel="stylesheet" href="https://example.com/design-system.css">`,
  css: `body { font-family: sans-serif; }`,
  js: `console.log("HtmlPreview loaded")`,
},
// or disable global injection:
htmlPreview: undefined,

claudeResources

Configures the Claude Code Resources Viewer, which auto-generates documentation pages from your .claude/ directory. Set to false to disable.

claudeResources: {
  claudeDir: ".claude",
},
// or disable:
claudeResources: false,

footer

Configures the site footer. When set to a FooterConfig object, renders a footer with link columns and optional copyright text. Set to false to disable the footer entirely.

Type: FooterConfig | false

Default: false

The FooterConfig object accepts:

Each FooterLinkColumn:

Each FooterLinkItem:

footer: {
  links: [
    {
      title: "Docs",
      locales: { ja: { title: "ドキュメント" } },
      items: [
        { label: "Getting Started", href: "/docs/getting-started", locales: { ja: { label: "はじめに" } } },
      ],
    },
    {
      title: "Community",
      items: [{ label: "GitHub", href: "https://github.com/my-org/my-repo" }],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Your Name.`,
},
// or disable footer:
footer: false,

headerNav

An array of navigation links rendered in the site header bar. Each item supports the following properties:

headerNav: [
  { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },
  { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
  { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
  { label: "Claude", labelKey: "nav.claude", path: "/docs/claude", categoryMatch: "claude" },
],

headerRightItems

Controls the items rendered in the right side of the site header, in order. Each item is a discriminated union on the type field.

Type: HeaderRightItem[]

headerRightItems: [
  { type: "component", component: "version-switcher" },
  { type: "trigger", trigger: "design-token-panel" },
  { type: "trigger", trigger: "ai-chat" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "search" },
  { type: "component", component: "language-switcher" },
  // custom external link:
  { type: "link", href: "https://example.com", label: "Blog", ariaLabel: "Blog" },
],

zfb Configuration

The root zfb.config.ts controls the build pipeline:

export default defineConfig({
  framework: "preact",
  tailwind: { enabled: true },
  collections,                  // derived from settings.docsDir + settings.locales
  adapter: "@takazudo/zfb-adapter-cloudflare",
  plugins: integrationPlugins,  // doc-history / search-index / llms-txt / claude-resources
});

Key aspects:

• framework: Preact — every component is a .tsx file (server-rendered by default; client islands hydrate via zfb's runtime)

• tailwind: First-class Tailwind CSS v4 integration

• collections: Generated from settings.docsDir and settings.locales, validated by zod schemas defined in the same file

• adapter: Cloudflare Workers — wraps the SSR bundle into dist/_worker.js, required for any route exporting prerender = false

• plugins: Each integration (doc-history, search-index, llms-txt, claude-resources) is a small wrapper module under ./plugins/ whose default export is a ZfbPlugin

• i18n routing: English (default at /docs/...) and additional locales declared in settings.locales. Default locale has no URL prefix

• Build-time highlighting: Powered by syntect (zfb's Rust pipeline) with a single fixed theme (base16-ocean-dark); not derived from colorScheme

Logo

The site logo is displayed on the landing page as a full-color banner image. The file is located at public/img/logo.svg.

The default banner is a 1200×630 SVG with the background baked in, so it renders correctly on both light and dark themes without any CSS masking. To update the logo, replace public/img/logo.svg with your own SVG file.

Because the banner is rendered as a plain <img> element, there are no constraints on background color or alpha channel — any SVG will display as-is.

Color Scheme Config

Color schemes are defined in src/config/color-schemes.ts. Each scheme provides 21 color properties:

• background, foreground, cursor, selectionBg, selectionFg

• palette — 16 color slots (palette[0] through palette[15])

• semantic (optional) — overrides for surface, muted, accent, accentHover, and more