設定

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

アクティブなカラースキーム名。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のbaseオプションに直接マッピングされます。

trailingSlash

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

デフォルト：false

trailingSlash: true,

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ルーティングにロケールを登録
• 言語切り替えに追加

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

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

docMetainfo

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

デフォルト：true

docTags

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

デフォルト：true

colorTweakPanel

インタラクティブなカラースキーム調整パネルを有効にします。trueの場合、ヘッダーにパレットアイコンが表示され、ページ下部に固定位置のパネルを開いて16色パレット、ベーステーマカラー、セマンティックトークンのオーバーライドをリアルタイムで編集できます。変更はlocalStorageに保存されます。

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

docHistory

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

ビルド時に、すべてのコンテンツファイルのgit履歴が抽出され、JSONファイルとしてdist/doc-history/に保存されます。開発モードでは、履歴はViteミドルウェア経由で動的に配信されます。

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

claudeResources

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

claudeResources: {
  claudeDir: ".claude",
},
// または無効化:
claudeResources: 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サポート、Reactアイランド、MiniSearch検索インデックス
• i18n：英語（デフォルト、/docs/...）と日本語（/ja/docs/...）。デフォルトロケールにはURLプレフィックスなし
• Tailwind CSS：Astroインテグレーションではなく@tailwindcss/viteプラグイン経由でロード
• Shikiテーマ：アクティブなカラースキームのshikiThemeプロパティから自動的に導出 — 手動同期不要

ロゴ

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

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

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のオーバーライド