設定

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

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

サイト設定

メインの設定ファイルはsrc/config/settings.tsです：

export const settings = {
  colorScheme: "Default Dark",
  colorMode: {
    defaultMode: "dark",
    lightScheme: "Default Light",
    darkScheme: "Default Dark",
    respectPrefersColorScheme: true,
  },
  siteName: "zudo-doc",
  siteDescription: "Documentation base framework...",
  base: "/",
  trailingSlash: true,
  docsDir: "src/content/docs",
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
  mermaid: true,
  noindex: false,
  editUrl: false,
  githubUrl: "https://github.com/zudolab/zudo-doc",
  siteUrl: "https://zudo-doc.takazudomodular.com",
  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",

すべての内部リンク（サイドバー、ナビゲーション、前後ページ、検索）にはベースパスが自動的にプレフィックスされます。この値はzfbのビルドパイプラインを通じて、出力されるアセットURLとルートパスに同じプレフィックスが適用されます。

trailingSlash

URLの末尾にトレイリングスラッシュを付けるかどうかを制御します。trueの場合、すべての内部リンクがトレイリングスラッシュ付きで生成されます（例：/docs/guidesではなく/docs/guides/）。@takazudo/zudo-doc/url-normalizerのビルド時URLヘルパーが、このポリシーを発行されるすべてのルートで強制します — ビルド時とデプロイホスト間でのルール分担についてはトレイリングスラッシュポリシーを参照してください。

デフォルト：true（ショーケースはtrueを設定しており、create-zudo-docでスキャフォールドしたプロジェクトもデフォルトでtrueです）

trailingSlash: true,

有効にすると、開発サーバーがトレイリングスラッシュなしのURLをトレイリングスラッシュ付きのURLへ301リダイレクトします（例：/docs/guides → /docs/guides/）。これにより、ローカルでも本番と同じナビゲーション挙動になります。静的アセット（.js、.css、.pngなどの拡張子を持つファイル）はリダイレクトの対象外です。

onBrokenMarkdownLinks

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

• "warn" — 警告をログに出力しますが、ビルドは継続します

• "error" — エラーをスローしてビルドを失敗させます

• "ignore" — 壊れたリンクを出力なしで無視します

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

デフォルト："warn"

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

docsDir

英語ドキュメントのMDXファイルが格納されるディレクトリパス（プロジェクトルートからの相対パス）。zfbのコンテンツエンジンがこのディレクトリをglobするため、プロジェクト内の任意の場所を指定できます。

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

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

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

defaultLocale

デフォルト（プレフィックスなし）ロケールのBCP 47コード。zfbのi18nルーターがルートの/docs/...ルートをマッピングするために使用します。

型：string

デフォルト："en"

defaultLocale: "en",

locales

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

デフォルト：{}

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

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

• zfbコンテンツコレクション（docs-{code}）を作成

• zfbのi18nルーティングにロケールを登録

• 言語切り替えに追加

defaultLocaleOnlyPrefixes

デフォルトロケールにのみ存在するURLプレフィックスの配列。これらのプレフィックス下のページは翻訳されず、どのロケールプレフィックス下にもミラーを持つべきではありません。該当ページでは言語切り替えがそれらを省略します。

型：string[]

デフォルト：[]

defaultLocaleOnlyPrefixes: [
  "/docs/claude-md/",
  "/docs/claude-skills/",
],

オーサリングワークフローの詳細についてはデフォルトロケール専用プレフィックスを参照してください。

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生成に必要です。

デフォルト：""

metaTags

出力される<meta>タグを細かく制御します。個々のサブフィールドをfalseに設定するとそのタグが省略されます。

型：MetaTagsConfig

metaTags: {
  description: true,
  keywords: false,
  ogImage: "/img/ogp.png",
  ogSiteName: true,
  twitterCard: "summary_large_image",
  twitterSite: "@yourbrand",
},

noindex

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

デフォルト：false

この設定が有効にする2つの補完的な動作（<meta name="robots">とrobots.txt）の詳細については、ロボットインデックス回避を参照してください。

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,

githubUrl

サイトヘッダーにGitHubリンクとして表示されるリポジトリURL。文字列を設定すると、そのURLへのGitHubアイコンリンクがヘッダー右側のアイテム（headerRightItems内でgithub-linkコンポーネントが配置された位置）に表示されます。ヘッダーのGitHubリンクを表示しないようにするにはfalseを設定します。

型：string | false

デフォルト：false（create-zudo-docのスキャフォールドでは無効。このショーケースではリポジトリURLを設定）

githubUrl: "https://github.com/my-org/my-repo",
// またはヘッダーのGitHubリンクを表示しない:
githubUrl: 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 の場合、またはページにタグが付いていない場合は効果がありません。

tagGovernance

タグボキャブラリーが有効な場合に適用される強制レベル。詳細なリファレンスはタグガバナンスを参照してください。

型："off" | "warn" | "strict"

デフォルト："warn"

tagVocabulary

tag-vocabulary.tsを実行時に参照するかどうか（エイリアス解決、非推奨フィルタリング、グループ化フッター）。falseに設定するとtagGovernanceに関わらずファイルを完全に無視します。詳細はタグガバナンスを参照してください。

型：boolean

デフォルト：true

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搭載のアシスタントが開きます。チャットAPIはCloudflare Workers SSRエンドポイント（pages/api/ai-chat.tsx）として動作します。wrangler.tomlにANTHROPIC_API_KEY、DOCS_SITE_URL、およびRATE_LIMIT KV名前空間の設定が必要です。

型：boolean

デフォルト：false

aiAssistant: true,

aiChatDemoMode

trueの場合、POST /api/ai-chatエンドポイントはAPIキー、KV名前空間、レートリミッターに触れることなく固定の「デモでは無効」返答を返します。実際のClaudeバックエンドを有効にする場合は、ANTHROPIC_API_KEYを設定した上でfalseに変更してください。

型：boolean

デフォルト：true

aiChatAllowedOrigins

aiChatDemoModeがfalseの場合にPOST /api/ai-chatへのCORSを許可するオリジン一覧。一致しないオリジンはAccess-Control-Allow-Originヘッダーを受け取らないため、ブラウザがリクエストをブロックします。空配列（デフォルト）はすべてのクロスオリジンブラウザリクエストをブロックし、同一オリジンからのリクエストは常に許可されます。

型：string[]

デフォルト：[]

aiChatAllowedOrigins: ["https://your-docs-site.example.com"],

aiChatGlobalDailyLimit

コスト抑制のためのグローバル日次リクエスト上限（オプション）。false（デフォルト）は上限なし。正の整数（例：500）を設定すると、その日のUTC日付内でその件数のリクエストが処理された時点でHTTP 429を返します。デモモードでは無効です。

型：number | false

デフォルト：false

aiChatGlobalDailyLimit: 500,

sidebarToggle

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

型：boolean

デフォルト：false

sidebarToggle: true,

sidebarResizer

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

型：boolean

デフォルト：false

sidebarResizer: true,

docHistory

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

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

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

bodyFootUtilArea

各ドキュメントページのボディ末尾のユーティリティアクションエリアに表示する項目を制御します。エリアを完全に非表示にするにはfalseを設定します。

型：BodyFootUtilAreaConfig | false

デフォルト：false

bodyFootUtilArea: {
  docHistory: true,
  viewSourceLink: true,
},
// またはエリアを非表示:
bodyFootUtilArea: false,

tocMinDepth

目次に含める最小見出し深さ（制限のみ：2〜4、デフォルト2）。3または4に上げると、より浅い見出しを目次から非表示にできます。2（h1は常にページタイトル）を下回ることもtocMaxDepthを超えることもできません。

型：number

デフォルト：2

tocMinDepth: 3, // h2見出しを目次から非表示にする

tocMaxDepth

目次に含める最大見出し深さ（制限のみ：2〜4、デフォルト4）。2または3に下げると、より深い見出しを目次から非表示にできます。4を超えることもtocMinDepthを下回ることもできません。

型：number

デフォルト：4

tocMaxDepth: 3, // h4見出しを目次から非表示にする

headingIdStrategy

見出しアンカーIDの生成方法を制御します。

• "flat"（zfbのデフォルト）— h2〜h6で共有する1つの重複カウンターを使ったgithub-sluggerスラグ（例：overview、overview-1）。

• "hierarchical" — 各見出しのスラグに祖先チェーンのプレフィックスを付けます（例：## Foo / ### Bar → foo、foo-bar）。フルパスで重複排除するため、アンカーの衝突が大幅に減少します。

"flat"から"hierarchical"への切り替えは、ネストされた見出しへの既存のディープリンクを破壊する変更です。

型："flat" | "hierarchical"

デフォルト："hierarchical"

headingIdStrategy: "flat",

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" },
],

headerRightItems

サイトヘッダーの右側にレンダリングされる項目を順番に制御します。各項目はtypeフィールドによる直和型です。

型：HeaderRightItem[]

headerRightItems: [
  { type: "component", component: "version-switcher" },
  { type: "trigger", trigger: "design-token-panel" },
  { type: "trigger", trigger: "ai-chat" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "search" },
  { type: "component", component: "language-switcher" },
  // カスタム外部リンク:
  { type: "link", href: "https://example.com", label: "Blog", ariaLabel: "Blog" },
],

zfb設定

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

export default defineConfig({
  framework: "preact",
  tailwind: { enabled: true },
  collections,                  // settings.docsDir + settings.localesから導出
  adapter: "@takazudo/zfb-adapter-cloudflare",
  plugins: integrationPlugins,  // doc-history / search-index / llms-txt / claude-resources
});

主なポイント：

• framework：Preact — すべてのコンポーネントは.tsxファイル（デフォルトでサーバーレンダリング、クライアントアイランドはzfbのランタイムでハイドレート）

• tailwind：Tailwind CSS v4のファーストクラスインテグレーション

• collections：settings.docsDirとsettings.localesから生成され、同じファイル内のzodスキーマで検証

• adapter：Cloudflare Workers — SSRバンドルをdist/_worker.jsにラップします。prerender = falseをエクスポートするルートに必須

• plugins：各インテグレーション（doc-history、search-index、llms-txt、claude-resources）は、./plugins/配下の小さなラッパーモジュールで、デフォルトエクスポートがZfbPlugin

• i18nルーティング：英語（デフォルト、/docs/...）とsettings.localesで宣言された追加ロケール。デフォルトロケールにはURLプレフィックスなし

• ビルド時ハイライト：syntect（zfbのRustパイプライン）による固定テーマ（base16-ocean-dark）で処理。colorSchemeの設定からは導出されません

ロゴ

サイトロゴはランディングページにフルカラーのバナー画像として表示されます。ファイルはpublic/img/logo.svgにあります。

デフォルトのバナーは背景が埋め込まれた1200×630のSVGで、CSSマスクなしでライト・ダーク両テーマで正しく表示されます。ロゴを更新するには、public/img/logo.svgを任意のSVGファイルに置き換えてください。

バナーは通常の<img>要素としてレンダリングされるため、背景色やアルファチャンネルに制約はありません — どんなSVGでもそのまま表示されます。

カラースキーム設定

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

• background、foreground、cursor、selectionBg、selectionFg

• palette — 16色スロット（palette[0]からpalette[15]）

• semantic（オプション）— surface、muted、accent、accentHoverなどのオーバーライド