設定

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

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

サイト設定

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

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

利用可能な組み込みスキーム：Dracula、Catppuccin Mocha、Nord、TokyoNight、Gruvbox Dark、Atom One Darkなど。

base

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

デフォルト："/"

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

base: "/my-docs",

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

docsDir

英語ドキュメントのMDXファイルが格納されるディレクトリパス（プロジェクトルートからの相対パス）。Astro 5の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}の形式になります。

mermaid

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

デフォルト：true

math

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

デフォルト：true

editUrl

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

デフォルト："https://github.com/user/repo/edit/main/"

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

docHistory

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

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

デフォルト：false

headerNav

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

複数のエントリを追加して異なるセクションにリンクできます：

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

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プロパティから自動的に導出 — 手動同期不要

カラースキーム設定

カラースキームは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のオーバーライド