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,
  colorTweakPanel: true,
  docMetainfo: true,
  docTags: true,
  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 base 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 trailingSlash to "always" or "never" accordingly.

Default: false

trailingSlash: true,

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

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

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

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

Default: true

colorTweakPanel

Enables an interactive color scheme tweak panel. When true, a palette icon appears in the header and users can open a fixed-position panel at the bottom of the page to edit all 16 palette colors, base theme colors, and semantic token overrides in real-time. Changes are persisted in localStorage.

Default: false (set to true to enable)

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.

At build time, git history is extracted for every content file and saved as JSON files to dist/doc-history/. In dev mode, history is served dynamically via a Vite middleware.

Default: false (set to true to enable)

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,

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, React 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 @takazudo/kumiko-gen. 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