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 astro.config.ts.

Site Settings

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

export const settings = {
  colorScheme: "Default Dark",
  colorMode: {
    defaultMode: "light",
    lightScheme: "Default Light",
    darkScheme: "Default Dark",
    respectPrefersColorScheme: true,
  },
  siteName: "zudo-doc",
  siteDescription: "Documentation base framework...",
  base: "/",
  trailingSlash: false,
  docsDir: "src/content/docs",
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
  mermaid: true,
  noindex: false,
  editUrl: false,
  siteUrl: "",
  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. This maps directly to Astro’s <code>base</code> config option.

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). This also sets Astro’s <code>trailingSlash</code> to "always" or "never" accordingly.

Default: false

trailingSlash: true,

When enabled, a middleware automatically redirects URLs without a trailing slash to their trailing-slash version with a 301 redirect (e.g., /docs/guides → /docs/guides/). This ensures consistent URLs during development, since Astro’s dev server does not perform this redirect on its own. Static assets (files with extensions like .js, .css, .png) and Astro internal paths (/_astro/, /_image) 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. This uses Astro’s glob() loader, so it can point to any directory.

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.

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 an Astro content collection (docs-{code})
• Registers the locale in Astro’s i18n routing
• Adds it to the language switcher

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

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

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,

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.

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. Requires a configured ai-chat-worker Cloudflare Worker backend.

Type: boolean

Default: false

aiAssistant: true,

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 @zudo-doc/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)

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" },
],

Astro Configuration

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

export default defineConfig({
  output: "static",
  integrations: [mdx(), react(), searchIndexIntegration()],
  i18n: {
    defaultLocale: "en",
    locales: ["en", ...Object.keys(settings.locales)],
    routing: { prefixDefaultLocale: false },
  },
  vite: {
    plugins: [tailwindcss()],
  },
  markdown: {
    shikiConfig: { theme: shikiTheme },
  },
});

Key aspects:

• output: Set to "static" for full static HTML export
• integrations: MDX support, Preact islands, and MiniSearch search indexing
• i18n: English (default at /docs/...) and Japanese (/ja/docs/...). Default locale has no URL prefix
• Tailwind CSS: Loaded via the @tailwindcss/vite plugin instead of an Astro integration
• Shiki theme: Automatically derived from the active color scheme’s shikiTheme property — no manual sync needed

Logo

The site logo is displayed on the landing page as a masked SVG shape. The file is located at public/img/logo.svg.

The default logo is a randomly generated geometric pattern created with <code>@takazudo/kumiko-gen</code>. To regenerate it with a new random pattern:

pnpm run generate:logo

You can also replace public/img/logo.svg with any custom SVG file. The logo is rendered as a CSS mask using the alpha channel, so:

• The SVG must have a transparent background — opaque backgrounds render as a filled rectangle
• The stroke or fill color in the SVG file does not matter; the displayed color is controlled by the site’s color tokens

Color Scheme Config

Color schemes are defined in src/config/color-schemes.ts. Each scheme provides 22 color properties plus a shikiTheme:

• background, foreground, cursor, selectionBg, selectionFg
• palette — 16 color slots (palette[0] through palette[15])
• shikiTheme — matching Shiki theme name for syntax highlighting
• semantic (optional) — overrides for surface, muted, accent, and accentHover