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: "Dracula",
  siteName: "zudo-doc",
  base: "/",
  docsDir: "src/content/docs",
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
  mermaid: true,
  headerNav: [
    { label: "Docs", path: "/docs" },
  ],
};

colorScheme

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

Available built-in schemes: Dracula, Catppuccin Mocha, Nord, TokyoNight, Gruvbox Dark, Atom One Dark, and many more.

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.

docsDir

The directory path (relative to the project root) where English documentation MDX files are stored. This uses Astro 5’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}.

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: "https://github.com/user/repo/edit/main/"

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

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

headerNav

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

You can add multiple entries to link to different sections:

headerNav: [
  { label: "Docs", path: "/docs" },
  { label: "Blog", path: "/blog" },
],

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

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