設定

zudo-docのグローバル設定と構成リファレンス。

zudo-docはsrc/config/ディレクトリ内の少数のファイルとルートのastro.config.tsで設定を行います。

サイト設定

メインの設定ファイルは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

アクティブなカラースキーム名。src/config/color-schemes.tsのキーと一致する必要があります。

利用可能な組み込みスキーム：Default Light、Default Dark。src/config/color-schemes.tsでカスタムスキームを追加できます。

colorMode

ライト/ダークモードの動作を設定します。カラーモード切り替えを完全に無効にしてcolorSchemeで指定されたスキームのみを使用するにはfalseに設定します。

有効にすると、ColorModeConfigオブジェクトを受け入れます：

colorMode: {
  defaultMode: "light",
  lightScheme: "Default Light",
  darkScheme: "Default Dark",
  respectPrefersColorScheme: true,
},
// またはカラーモード切り替えを無効化:
colorMode: false,

base

サブディレクトリにデプロイする際のベースパス。サイトがルートドメインではなくサブパスから配信される場合に設定します。

デフォルト："/"

例えば、サイトをhttps://example.com/my-docs/で配信する場合：

base: "/my-docs",

すべての内部リンク（サイドバー、ナビゲーション、前後ページ、検索）にはベースパスが自動的にプレフィックスされます。これはAstroのConfigの<code>base</code>オプションに直接マッピングされます。

trailingSlash

URLの末尾にトレイリングスラッシュを付けるかどうかを制御します。trueの場合、すべての内部リンクがトレイリングスラッシュ付きで生成されます（例：/docs/guidesではなく/docs/guides/）。これにより、Astroの<code>trailingSlash</code>も"always"または"never"に設定されます。

デフォルト：false

trailingSlash: true,

有効にすると、ミドルウェアがトレイリングスラッシュなしのURLをトレイリングスラッシュ付きのURLへ301リダイレクトします（例：/docs/guides → /docs/guides/）。Astroの開発サーバーはこのリダイレクトを自動的に行わないため、開発時でも一貫したURLを保証します。静的アセット（.js、.css、.pngなどの拡張子を持つファイル）やAstro内部パス（/_astro/、/_image）はリダイレクトの対象外です。

onBrokenMarkdownLinks

ビルド中に壊れた内部マークダウンリンクをどのように処理するかを制御します。zudo-docのリンクリゾルバープラグインが解決する相対 [テキスト](./page.mdx) リンクに適用されます。

• "warn" — 警告をログに出力しますが、ビルドは継続します
• "error" — エラーをスローしてビルドを失敗させます
• "ignore" — 壊れたリンクを出力なしで無視します

型："warn" | "error" | "ignore"

デフォルト："warn"

onBrokenMarkdownLinks: "error", // 壊れたリンクでビルドを失敗させる

docsDir

英語ドキュメントのMDXファイルが格納されるディレクトリパス（プロジェクトルートからの相対パス）。Astroのglob()ローダーを使用するため、任意のディレクトリを指定できます。

デフォルト："src/content/docs"

docsDir: "docs",  // プロジェクトルートの./docs/にコンテンツを配置

これはDocusaurusのdocs.pathオプションに似ています — zudo-docをドキュメントがプロジェクトルートレベルにある大規模プロジェクトのドキュメントツールとして使用する場合に便利です。

locales

追加ロケール設定のマップ。各キーはロケールコードで、値はlabel（言語切り替えの表示名）とdir（コンテンツディレクトリパス）を持つオブジェクトです。

デフォルト：{}

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

各ロケールエントリに対して、zudo-docは自動的に：

• Astroコンテンツコレクション（docs-{code}）を作成
• Astroのi18nルーティングにロケールを登録
• 言語切り替えに追加

versions

マルチバージョンドキュメントを設定します。VersionConfigオブジェクトの配列を設定すると、zudo-docはバージョン管理されたコンテンツコレクションを作成し、サイドバーにバージョン切り替えを追加します。各バージョンのセクションは/v/{slug}/docs/でアクセスできます。バージョン管理を無効にするにはfalseを設定します。

型：VersionConfig[] | false

デフォルト：false

各VersionConfigオブジェクトは以下のプロパティを受け入れます：

versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    banner: "unmaintained",
  },
],
// またはバージョン管理を無効化:
versions: false,

siteName

ヘッダーに表示され、ページタイトルに使用されるサイト名。ページタイトルは{ページタイトル} | {siteName}の形式になります。

siteDescription

サイトの短い説明。SEOやソーシャルシェアリングのメタタグに使用されます。

デフォルト：""

siteUrl

サイトの完全なベースURL（例："https://example.com"）。サイトマップでの絶対URL生成に必要です。

デフォルト：""

noindex

trueの場合、すべてのページにnoindexとnofollowメタタグを追加します。検索エンジンにインデックスされるべきでない内部ドキュメントサイトに便利です。

デフォルト：false

mermaid

Mermaidダイアグラムのサポートを有効にします。trueの場合、mermaid言語識別子を持つフェンスコードブロックがダイアグラムとしてレンダリングされます。falseの場合、mermaidコードブロックはプレーンコードとして表示されます。

デフォルト：true

math

KaTeX数式レンダリングを有効にします。trueの場合、インライン数式（$...$）、ブロック数式（$$...$$）、およびフェンスmathコードブロックが数式としてレンダリングされます。

デフォルト：true

cjkFriendly

CJKフレンドリーなタイポグラフィ調整を有効にします。trueの場合、ドキュメント全体の中国語、日本語、韓国語テキストに対して改善された改行およびワードラップの動作を適用します。

型：boolean

デフォルト：false

cjkFriendly: true,

editUrl

「このページを編集」リンクのベースURL。完全なURLはeditUrl + contentDir + "/" + entryIdとして構築されます。編集リンクを無効にするにはfalseに設定します。

デフォルト：false（無効）

editUrl: "https://github.com/my-org/my-repo/edit/main/",
// または無効化:
editUrl: false,

sitemap

ビルド時に自動sitemap.xml生成を有効にします。サイトマップには404を除くすべてのビルド済みHTMLページが含まれます。

デフォルト：true

llmsTxt

ビルド時に自動llms.txt生成を有効にします。trueの場合、すべてのドキュメントページをタイトルと説明とともにリスト化したllms.txtファイルがサイトルートに生成されます。このファイルはllms.txt仕様に従っており、AIアシスタントがドキュメントコンテンツを発見・インデックス化するのに役立ちます。

型：boolean

デフォルト：false

llmsTxt: true,

docMetainfo

ページタイトルの下にメタデータ（作成日、最終更新日、著者）を表示します。日付と著者はビルド時にgit履歴から抽出されます。

デフォルト：true

docTags

ドキュメントページのタグサポートを有効にします。trueの場合、ページはtagsフロントマターフィールドを使用でき、タグインデックスページが/docs/tags/に生成されます。

詳しい使い方はタグガイドを参照してください。

デフォルト：true

tagPlacement

ドキュメントページに表示されるタグバッジ列の位置を制御します。

型："after-title" | "before-pager"

デフォルト："after-title"

• "after-title" — ページタイトルの直下、本文の上にバッジ列を表示します。
• "before-pager" — コンテンツの末尾、前後ページャーのすぐ上にバッジ列を表示します。

tagPlacement: "before-pager",

docTags が false の場合、またはページにタグが付いていない場合は効果がありません。

frontmatterPreview

カスタムフロントマターフィールドをページタイトルの直下にコンパクトなキー/値テーブルとして表示します。フレームワーク管理のキー（title、description、sidebar_position など）はデフォルトで非表示になるため、プロジェクト固有のメタデータのみが表示されます。すべてのページでブロックを無効にするには false を設定します。

型：FrontmatterPreviewConfig | false

デフォルト：{}（組み込み無視リストで有効）

FrontmatterPreviewConfig オブジェクトは以下を受け入れます：

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

インタラクティブなDesign Token Panelを有効にします。trueの場合、ヘッダーにパレットアイコンが表示され、タブ型のパネルを開いてスペーシング・フォント・サイズ・カラーの各トークンをリアルタイムで編集できます。変更はlocalStorageに保存され、JSONとしてエクスポート／インポートできます。

デフォルト：false（trueに設定して有効化）

aiAssistant

AIアシスタントチャットウィジェットを有効にします。trueの場合、ページにチャットボタンが表示され、ドキュメントに関する質問に答えるAI搭載のアシスタントが開きます。設定済みのai-chat-worker Cloudflare Workerバックエンドが必要です。

型：boolean

デフォルト：false

aiAssistant: true,

sidebarToggle

サイドバー折り畳みトグルを有効にします。trueの場合、サイドバーヘッダーのボタンでユーザーがサイドバーを完全に折り畳むことができ、コンテンツの水平スペースが広がります。折り畳み状態はlocalStorageに保存されます。

型：boolean

デフォルト：false

sidebarToggle: true,

sidebarResizer

サイドバー幅のリサイズを有効にします。trueの場合、サイドバーの右端にドラッグハンドルが表示され、ユーザーがサイドバー幅をドラッグして調整できます。リサイズ後の幅はlocalStorageに保存されます。

型：boolean

デフォルト：false

sidebarResizer: true,

docHistory

ドキュメントごとのgitリビジョン履歴ビューアを有効にします。trueの場合、各ドキュメントページにHistoryボタンが表示され、ドキュメントのgitコミット履歴と行単位のdiffビューアを備えたサイドパネルが開きます。

開発モードでは、履歴はポート4322で動作するスタンドアロンの@zudo-doc/doc-history-serverパッケージが配信します。本番環境では、CLIジェネレーターがCI中に静的JSONファイルを生成します。サーバーとCLIの詳細についてはDoc History Serverリファレンスを参照してください。

デフォルト：false（trueに設定して有効化）

htmlPreview

<HtmlPreview>コンポーネントのグローバル設定です。設定すると、指定したhead、css、jsがサイト上のすべての<HtmlPreview> iframeに注入されます。共有フォント、デザインシステムのスタイルシート、ユーティリティスクリプトを各コンポーネントデモで繰り返すことなく読み込む際に便利です。

グローバル注入を無効にするにはundefined（デフォルト）に設定します。

型：HtmlPreviewConfig | undefined

デフォルト：undefined

HtmlPreviewConfigオブジェクトは以下のプロパティを受け入れます：

htmlPreview: {
  head: `<link rel="stylesheet" href="https://example.com/design-system.css">`,
  css: `body { font-family: sans-serif; }`,
  js: `console.log("HtmlPreview loaded")`,
},
// またはグローバル注入を無効化:
htmlPreview: undefined,

claudeResources

Claude Codeリソースビューアを設定します。.claude/ディレクトリからドキュメントページを自動生成します。無効にするにはfalseに設定します。

claudeResources: {
  claudeDir: ".claude",
},
// または無効化:
claudeResources: false,

footer

サイトフッターを設定します。FooterConfigオブジェクトを設定すると、リンク列とオプションの著作権テキストを含むフッターがレンダリングされます。フッターを完全に無効にするにはfalseを設定します。

型：FooterConfig | false

デフォルト：false

FooterConfigオブジェクトは以下を受け入れます：

各FooterLinkColumn：

各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.`,
},
// またはフッターを無効化:
footer: false,

headerNav

サイトヘッダーバーにレンダリングされるナビゲーションリンクの配列。各アイテムは以下のプロパティをサポートします：

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設定

ルートのastro.config.tsがビルドパイプラインを制御します：

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 },
  },
});

主なポイント：

• output：完全な静的HTMLエクスポートのため"static"に設定
• integrations：MDXサポート、Preactアイランド（compatモード）、MiniSearch検索インデックス
• i18n：英語（デフォルト、/docs/...）と日本語（/ja/docs/...）。デフォルトロケールにはURLプレフィックスなし
• Tailwind CSS：Astroインテグレーションではなく@tailwindcss/viteプラグイン経由でロード
• Shikiテーマ：アクティブなカラースキームのshikiThemeプロパティから自動的に導出 — 手動同期不要

ロゴ

サイトロゴはランディングページにマスクされたSVGシェイプとして表示されます。ファイルはpublic/img/logo.svgにあります。

デフォルトのロゴは<code>@takazudo/kumiko-gen</code>で生成されたランダムな幾何学パターンです。新しいランダムパターンで再生成するには：

pnpm run generate:logo

public/img/logo.svgを任意のカスタムSVGファイルに置き換えることもできます。ロゴはアルファチャンネルを使ったCSSマスクとしてレンダリングされるため：

• SVGは透明な背景が必須です — 不透明な背景は塗りつぶされた矩形としてレンダリングされます
• SVGファイル内のストロークや塗りの色は関係ありません。表示色はサイトのカラートークンで制御されます

カラースキーム設定

カラースキームはsrc/config/color-schemes.tsで定義されます。各スキームは22のカラープロパティとshikiThemeを提供します：

• background、foreground、cursor、selectionBg、selectionFg
• palette — 16色スロット（palette[0]からpalette[15]）
• shikiTheme — シンタックスハイライト用の対応するShikiテーマ名
• semantic（オプション）— surface、muted、accent、accentHoverのオーバーライド