設定
唯一の zudoDoc() 設定リファレンス — 全フィールドとそのデフォルト。
zudo-doc プロジェクトは1つのファイルで設定します。ルートの zfb.config.ts です。変更したいフィールドを付けて zudoDoc() を呼び出し、それ以外の設定はすべて文書化されたデフォルトにフォールバックします。
import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";
export default defineConfig(
zudoDoc({
siteName: "My Docs",
// …only the fields you chose; everything has a documented @default.
}),
);zudoDoc() はあなたのフィールドをパッケージデフォルトの上にフィールド単位でマージし（あなたが勝つ）、上書きしない限りパッケージのデータデフォルト（フロントマタースキーマ、ディレクティブ語彙、翻訳、カラースキーム、タグ語彙）を供給し、完全な ZfbConfig を返します — あなたは何もスプレッドしません。
Note
ZudoDocConfig 型がこのリファレンスの唯一の情報源です。すべてのフィールドは @default の JSDoc 注釈を持ち、IDE のホバーで表示されます。以下の表はそのデフォルトをそのまま反映しています。このページと型が食い違う場合は、型が正しいです。
Info
ここでのデフォルトは、新規の create-zudo-doc プロジェクトが継承するパッケージデフォルトです。このショーケースはそれらのフィールドを明示的に渡すことで、はるかに多くを有効化しています（ほとんどの機能オン、i18n、フルのヘッダーナビ）。ショーケースのリッチな設定をデフォルトのベースラインとして読まないでください。
ホームページ
home
パッケージ所有のホームページに対するレイアウト設定です。デフォルトでは、 ホームのコンテンツ帯は標準のサイドバーなし幅になります。
デフォルト: { wide: false }
大きな複数列のカテゴリグリッドでビューポートの大部分を使いたい場合は、 wide を true にします。
export default defineConfig(
zudoDoc({
siteName: "My Docs",
home: { wide: true },
}),
);この設定は / と / のようなロケール接頭辞付きホームページの両方に 適用されます。パッケージ所有ルートを通して動作するため、スキャフォールドの ルートページはロックされた1行の再エクスポートのままです。
export { default } from "@takazudo/zudo-doc/routes/index";型: { wide?: boolean } · デフォルト: { wide: false }
アイデンティティと URL
siteName
ヘッダーとメタデータに表示されるサイト名。ページタイトルは {page title} | {siteName} としてレンダリングされます。ほぼ必ず設定する唯一のフィールドです。
デフォルト: "Docs"
siteDescription
メタデータ（<meta name="description">、llms.txt）で使われるサイト説明。
デフォルト: ""
logo
ホームのヒーローに表示するロゴ。"auto"（デフォルト）は siteName をシードにした決定論的な生成 SVG — フレーム付きの「装飾プレート」マーク — を描画します。ライト/ダークに自動追従するため、新規プロジェクトでもアセットなしで見栄えのするヒーローになります。パス文字列（例 "/）を指定すると自前のアセットをテーマ適応の CSS マスクとして描画し、false でロゴブロック自体を非表示にします。
npx zudo-doc eject logo を実行すると、生成されたマークを実ファイルとして実体化できます — public/ を書き出し、このフィールドを "/ に切り替えます。これにより、リクエスト時に生成されるデフォルトの代わりに、編集・差し替え・別用途（OGP など）での再利用ができる実ファイルを所有できます。CLI フラグについてはカスタマイズ → 第5段を参照してください。
デフォルト: "auto"
siteUrl
サイトマップ / canonical / og:url のための正規サイトオリジン（例 "https:）。空 = 未設定。
デフォルト: ""
base
すべての絶対アセット URL の前にマウントされる公開 URL サブパスプレフィックス（例 "/pj/my-site/"）。"/" = ルートマウント。すべての内部リンク（サイドバー、ナビ、prev/next、検索）は自動的にプレフィックスされます。
デフォルト: "/"
Note
MDX 内のインラインマークダウンリンク（例 [text](/docs/some-page)）は非ルート base 向けに書き換えられません — 代わりにコンテンツでは相対リンクを使ってください。
trailingSlash
拡張子なしの内部 href に末尾の / を付けます。
デフォルト: false
このルールがビルド時とデプロイホストの間でどう分かれるかは末尾スラッシュポリシーを参照してください。
minifyHtml
zfb build の本番 HTML 出力をミニファイします。デバッグ時に読める出力にするには false にします。
デフォルト: true
githubUrl
ヘッダーに表示される GitHub リポジトリ URL（github-link ヘッダー項目経由）、または省略するなら false。
型: string | false · デフォルト: false
editUrl
「このページを編集」リンクのベース、または省略するなら false。完全な URL は editUrl + contentDir + "/" + entryId です。
型: string | false · デフォルト: false
noindex
すべてのページに noindex,nofollow を付けます（内部ドキュメント向け）。
デフォルト: false
検索エンジンのインデックス回避を参照してください。
head
サイト全体のカスタム <head> 追加要素（preconnect / preload / stylesheets / meta / alternateLinks）。追加を出力しないなら省略。
型: SiteHeadConfig · デフォルト: undefined
metaTags
<meta> / OpenGraph / Twitter カードの出力トグル。
デフォルト: { description: true, keywords: false, ogImage: false, ogSiteName: true, twitterCard: false }
| プロパティ | 型 | 説明 |
|---|---|---|
description | boolean | <meta name="description"> を出力 |
keywords | string | false | <meta name="keywords"> の値、または省略 |
ogImage | string | false | og:image / twitter:image のパス、または省略 |
ogSiteName | boolean | og:site_name を出力 |
twitterCard | "summary" | "summary_large_image" | false | Twitter カードの種類、またはブロックを省略 |
twitterSite | string（任意） | twitter:site ハンドル |
twitterCreator | string（任意） | twitter:creator ハンドル |
sitemap
サイトマップルートを出力します。
デフォルト: false
metaTags と sitemap を組み合わせたソーシャル共有・検索インデックス設定の全体像は SEO ガイド も参照してください。
onBrokenMarkdownLinks
.md/.mdx リンクが解決できないときの挙動: "warn" はログして続行、"error" はビルドを失敗、"ignore" は無音。
型: "warn" | "error" | "ignore" · デフォルト: "warn"
カラー
colorScheme
アクティブなカラースキーム名（colorSchemes に存在する必要があります）。バンドルされる2つのスキームは Default Light と Default Dark です。
デフォルト: "Default Dark"
colorMode
ライト/ダークモードの配線、または単一固定スキームなら false。
デフォルト: { defaultMode: "dark", lightScheme: "Default Light", darkScheme: "Default Dark", respectPrefersColorScheme: true }
| プロパティ | 型 | 説明 |
|---|---|---|
defaultMode | "light" | "dark" | ユーザー設定適用前の初期モード |
lightScheme | string | ライトモードで使うスキーム |
darkScheme | string | ダークモードで使うスキーム |
respectPrefersColorScheme | boolean | OS レベルのライト/ダーク設定に合わせる |
colorMode: false, // single fixed scheme (colorScheme only)ランプネイティブなモデルとカスタムスキームの追加（下記の colorSchemes エスケープハッチ経由）については Color リファレンスを参照してください。
テーマパック
テーマパックは、上記のカラースキームシステムの上に重なるインストール可能なデザインバンドルです — すべてのパックがライト/ダーク両方の値を定義するため、モードトグルはどのパックでもそのまま機能します。スイッチャー UI、theme CLI、パックの作り方はテーマパックリファレンスを参照してください。
themePack
アクティブなテーマパックのスラッグ。"default" は zudo-doc 標準の見た目です（パックのスタイルシートは読み込まれません）。解決済みの themePacks リストのメンバーである必要があり、未知のスラッグはビルドを大きな声で失敗させます。
デフォルト: "default"
themePackSwitcher
右下のテーマパックスイッチャーフライアウト（と一覧ダイアログ）を全ページにマウントします。
デフォルト: false
themePacks
有効化するパックのスラッグをスイッチャー順で並べたリスト — この並び順がそのままスイッチャーの Prev/Next の巡回順と一覧ダイアログのグリッド順になります。undefined は同梱パックすべてを有効化します（"default" が先頭、残りはアルファベット順）。明示的なリストが正となります — "default" を省いても、自由に並べ替えても構いませんが、重複や未知のスラッグはビルドを大きな声で失敗させます。
デフォルト: undefined
themePacks: ["default", "foundry"],コンテンツと i18n
docsDir
デフォルトロケールのドキュメントを保持するディレクトリ（プロジェクトルート相対）。
デフォルト: "src/
entryDocSlug
バージョン一覧ページが「最新ドキュメント」へのエントリーポイント（および過去の各バージョンのドキュメントリンク）として使用するドキュメントページのルートスラッグ。先頭・末尾にスラッシュを含まない（例："getting-started"、"overview/getting-started"）。実行時のバリデーションは行われず、無効なスラッグは単に404になる。
デフォルト: "getting-started"
defaultLocale
デフォルトロケールコード（プレフィックスなしのルート）。
デフォルト: "en"
locales
追加ロケール: コード → { label, dir }。それぞれが / ルートツリーと docs-<code> コレクションになります。
デフォルト: {}
locales: {
ja: { label: "JA", dir: "src/content/docs-ja" },
},defaultLocaleOnlyPrefixes
デフォルトロケールのみで提供されるルートプレフィックス（ロケールプレフィックスされない）。言語切り替えは該当ページでこれらを省略します。
デフォルト: []
デフォルトロケール限定プレフィックスを参照してください。
versions
ドキュメントのバージョン、または単一（バージョンなし）のドキュメントセットなら false。各バージョンセクションは / で提供されます。
型: VersionConfig[] | false · デフォルト: false
| プロパティ | 型 | 説明 |
|---|---|---|
slug | string | URL パス内のバージョン識別子 |
label | string | バージョン切り替えの表示ラベル |
docsDir | string | このバージョンのデフォルトロケールドキュメントのディレクトリ |
locales | Record（任意） | このバージョンのロケール別コンテンツディレクトリ |
banner | "unmaintained" | "unreleased" | false（任意） | このバージョンのページに表示するバナー |
バージョニングガイドを参照してください。
mermaid
マークダウンでの mermaid ダイアグラムレンダリングを有効化します。
デフォルト: true
math
KaTeX 数式レンダリング（$…$、$$…$$、フェンス math）を有効化します。
デフォルト: false
cjkFriendly
zfb の CJK フレンドリーな改行 / 強調処理を有効化します。
デフォルト: false
タグ
tagVocabulary と tagGovernance は直交しています — 一方はランタイムのゲート、もう一方は強制レベルです。語彙のエントリは tagVocabularyEntries エスケープハッチで別途供給します。
docTags
/ + / タグインデックスルートを有効化します。
デフォルト: false
tagPlacement
コンテンツに対してページ単位のタグをどこにレンダリングするか。
型: "after-title" | "before-pager" · デフォルト: "after-title"
tagGovernance
語彙が参照されるときのタグガバナンス強制レベル（"off" / "warn" / "strict"）。
デフォルト: "off"
tagVocabulary
タグ語彙がランタイムで参照されるか（正確な id の認識、グループ化フッター）。tagGovernance と直交。これはブールゲートで、エントリ自体は tagVocabularyEntries から来ます。
デフォルト: false
タグガバナンスを参照してください。
目次と見出し
tocMinDepth
TOC に含まれる最小見出し深度（2〜4）。
デフォルト: 2
tocMaxDepth
TOC に含まれる最大見出し深度（2〜4）。
デフォルト: 4
サイト設定
designTokenPanel
スペーシング・フォント・サイズ・カラートークンをライブ編集するインタラクティブな Design Token Panel（zdtp）を有効化します。
デフォルト: false
パネルは追加設定なしで動作します。完全にカスタマイズするには、designTokenPanelConfigModule をホストモジュールに向けます — ホストクロームバインディングを参照してください。
sidebarResizer
ドラッグ可能なサイドバーリサイザーを有効化します。
デフォルト: false
sidebarToggle
デスクトップのサイドバー折りたたみトグルを有効化します。
デフォルト: false
tocToggle
デスクトップの目次折りたたみトグルを有効化します。xl 幅（1280px 以上）の画面で、ビューポート右端にシェブロンボタンが固定表示されます。
デフォルト: false
目次を畳むと、空いた幅はそのままコンテンツ側に渡ります。ここがこの機能の狙いで、横に広いテーブルや長い行のコードブロックが、折り返しや横スクロールなしで読めるようになります。読者が選んだ状態は保存されるため、ページを移動しても、次に訪れたときも維持されます。
このトグルが効くのはパッケージ標準の目次だけです。chromeBindingsModule で Toc スロットを差し替えている場合、独自のコンポーネントはそのまま描画され、トグルも表示されません。ホストクロームバインディングを参照してください。
tocToggle と hide_toc の違い
この2つは解決する問題が別で、併用もできます。hide_toc フロントマターは書き手の判断をビルド時に焼き込むものです。そのページは目次を持たない状態で配信され、読者が呼び戻すことはできません。一方 tocToggle は読者のための操作です。標準の目次が描画されるページであれば、いま表示するかどうかを読者が決められます。hide_toc ですでに目次を落としたページには何の影響もありません。
imageEnlarge
コンテンツ画像のクリック拡大を有効化します。
デフォルト: false
findInPage
body-end islands に FindInPageInit アイランド（Cmd/Ctrl+F 検索バー）をマウントします。
デフォルト: false
生成された Tauri スキャフォールドに対して create-zudo-doc の tauri フィーチャーが自動的に有効化します(tauri フィーチャー選択時にジェネレーターが findInPage: true を出力します。次回の create-zudo-doc リリースで反映されます)。window.__TAURI_INTERNALS__ で自己ゲートするため、true の場合でも Tauri シェル外では安全に何もしません（no-op）。BodyEndIslands クロームバインディングスロット(ChromeHostBindings の一部 — この仕組み全般についてはホストクロームバインディングを参照)を上書きするホストは、アイランド自体をマウントする必要があります — パッケージのデフォルトはスロットが未設定の場合にのみ適用されます。
dynamicPageTransition
動的（ビュートランジション）ページ読み込みオーバーレイを有効化します。
デフォルト: false
frontmatterPreview
フロントマタープレビュー設定（無視キーの上書き）、またはプレビューパネルを無効化するなら false。
型: FrontmatterPreviewConfig | false · デフォルト: false
| プロパティ | 型 | 説明 |
|---|---|---|
ignoreKeys | string[]（任意） | デフォルトの無視リストを置き換える |
extraIgnoreKeys | string[]（任意） | デフォルトに追加（ignoreKeys があると無視される） |
フロントマタープレビューリファレンスを参照してください。
docHistory
ページ単位の git 履歴（Created/Updated + ドロップダウン）を有効化します。dev では @takazudo/zudo-doc-history-server がポート 4322 で履歴を提供し、CI ではジェネレーターが静的 JSON を出力します。
デフォルト: false
Note
新しい scaffold は、この機能を選択したとき、スキャナーから到達可能な実際の DocHistory アイランドを生成されるすべてのドキュメントルート形状へ配線します。履歴ボタン自体には chromeBindingsModule もルート編集も不要です。
ドキュメント履歴ガイドを参照してください。
docMetainfo
ドキュメントページに Created/Updated/Author メタブロックを表示します（ビルド時に git 履歴から抽出）。
デフォルト: false
メタデータにはホスト binding が必要です
docHistoryMeta スロットのデフォルトは {} です。chromeBindingsModule をビルド時の履歴マニフェストへバインドするモジュールに向けてください。新しいルートスタブはそのモジュールをすでに消費するため編集しません。詳しくは Custom Components と ホストクロームバインディングを参照してください。
bindingsモジュールはdocHistoryMetaを提供する必要があります。デフォルトの{}データスロットでは、描画するメタデータブロックがありません。組み合わせるdocHistory設定についてはドキュメント履歴ガイドを参照してください。
bodyFootUtilArea
body-foot ユーティリティエリア（doc-history / view-source）、または無効化するなら false。
型: BodyFootUtilAreaConfig | false · デフォルト: false
| プロパティ | 型 | 説明 |
|---|---|---|
docHistory | boolean（任意） | History ボタンを表示（docHistory: true が必要） |
viewSourceLink | boolean（任意） | 生ソースリンクを表示（githubUrl が必要） |
htmlPreview
グローバルな HTML プレビューサンドボックス設定、または各 <HtmlPreview> iframe へのグローバル注入を無効化するなら undefined。
型: HtmlPreviewConfig | undefined · デフォルト: undefined
| プロパティ | 型 | 説明 |
|---|---|---|
head | string（任意） | <head> に注入する生 HTML |
css | string（任意） | <style> ブロックとして注入する CSS |
js | string（任意） | </body> の前に注入する JS |
footer
フッター設定（リンクカラム / コピーライト / タグリスト）、またはフッターなしなら false。
型: FooterConfig | false · デフォルト: false
| プロパティ | 型 | 説明 |
|---|---|---|
links | FooterLinkColumn[] | リンクカラム |
copyright | string（任意） | コピーライトテキスト（HTML 可） |
各 FooterLinkColumn は title、items（{ label, href }[]）、および任意のロケール別上書きを持ちます。
headerNav
ヘッダーの主要ナビゲーション項目。
デフォルト: []
| プロパティ | 型 | 説明 |
|---|---|---|
label | string | 表示テキスト |
labelKey | string（任意） | i18n 翻訳キー（label を上書き） |
path | string | 遷移先パス |
categoryMatch | string（任意） | このタブをサイドバーカテゴリにリンク |
versioned | boolean（任意） | このアイテムのリンクがアクティブな / プレフィックスを持つかどうか。デフォルトは true — ヘッダーナビゲーションを参照 |
headerNav: [
{ label: "Guides", path: "/docs/guides", categoryMatch: "guides" },
{ label: "Reference", path: "/docs/reference", categoryMatch: "reference" },
],ナビゲーションの構成方法を参照してください。
headerRightItems
ヘッダー右側の項目（トグル、スイッチャー、リンク）を順に。
デフォルト: [{ type: "component", component: "theme-toggle" }]
type | 追加フィールド | 説明 |
|---|---|---|
"component" | component — "theme-toggle", "language-switcher", "version-switcher", "github-link", "search" | 組み込みヘッダーコンポーネント |
"trigger" | trigger — "design-token-panel", "ai-chat" | パネルを開く（機能が必要） |
"link" | href, label?, ariaLabel?, icon? | カスタムリンク |
"html" | html | 生 HTML |
AI アシスタント
aiAssistant
AI チャットアシスタントルート（/、SSR）を有効化します。
デフォルト: false
ライブアシスタントの実行にはデプロイアダプター、IPごとのKV、Anthropicシークレット、そして正確な 上限を有効にする場合はAI_CHAT_DAILY_SPEND_CAP Durable Object migrationが必要です — カスタマイズ → デプロイ経路とAI Assistant APIを参照してください。これらはhost-ownedな部品です。package/scaffoldが提供するのは安全なplaceholder routeであり、showcaseのlive handler、Worker entry、Durable Object classではありません。
aiChatDemoMode
/ を固定の「無効」応答でショートサーキットします（API キー、KV、Durable Object、レートリミッター、provider fetchに触れません）。ライブの Claude 対応チャットを有効化するには false にします。
デフォルト: false
aiChatAllowedOrigins
デモモードでないときの / の許可 CORS オリジン。空 = すべてのクロスオリジンブラウザリクエストをブロック。
デフォルト: []
aiChatGlobalDailyLimit
/の全IPを合算したUTC日ごとの正確なAnthropic fetch許可上限です。falseなら 正確な上限を無効化します。provider/network障害でも許可枠は返却しません。
型: number | false · デフォルト: false
生成とインテグレーション
llmsTxt
ドキュメントを要約する llms.txt ルートを出力します。
デフォルト: false
llms.txtを参照してください。
changelogs
Changelog 生成設定、または無効化するなら false。
デフォルト: false
Changelog ガイドを参照してください。
claudeResources
Claude リソースの取り込み設定、または無効化するなら false。
型: { claudeDir; projectRoot?; scanRoot? } | false · デフォルト: false
claudeResources: { claudeDir: ".claude" },Claude Resources ガイドを参照してください。
ルーティングの継ぎ目
packageOwnedRoutes
ビルド時のパッケージ所有ルート注入。true のとき、ドキュメントルートはパッケージから注入されます（プロジェクト側の pages/*.tsx レイアウトスタブは不要）。プロジェクトが自前のドキュメントルートスタブを出荷する場合のみ false にします。
デフォルト: true
chromeBindingsModule
defineChromeBindings（@takazudo/）で構築した chromeBindings オブジェクトをエクスポートするホストモジュールへのプロジェクトルート相対パス（packageOwnedRoutes がオンのときのみ消費）。注入されたクロームシムをパッケージデフォルトのスタブのままにするなら省略。
デフォルト: undefined
ホストクロームバインディングを参照してください。
エスケープハッチフィールド
これらは非シリアライズ可能 / データデフォルトを上書きします。JSON シリアライズではなくインポートグラフを通じて移動するため、関数、Zod 型、コンポーネントマップを運べます。
buildDocsSchema
デフォルトのドキュメントフロントマター Zod スキーマビルダーを完全に置き換えます。省略時、zudoDoc() はパッケージデフォルト（@takazudo/）を構築します（ガバナンス対応。tagGovernance + tagVocabularyEntries から導出）。
型: () => ZodType · デフォルト: undefined（パッケージデフォルトを使用）
これがカスタムフロントマターキーを追加する方法です — カスタマイズ → 第1段を参照してください。
colorSchemes
カラースキームのパレットマップを上書きします。省略時、出荷済みの2スキーム（Default Light / Default Dark）を使います。
型: Record<string, ColorScheme> · デフォルト: undefined
translations
UI 文字列の翻訳テーブルを上書きします。省略時、出荷済みの en/ja/de デフォルトを使います。
型: PresetTranslations · デフォルト: undefined
directives
ディレクティブ → JSX コンポーネント名マップを上書きします。省略時、標準の7つを使います。
型: DirectiveVocabulary · デフォルト: undefined
Warning
directivesはボキャブラリ全体を置き換えます。1つ追加するときも標準のディレクティブを保持してください。そうしないと、既存の:::note、:::warningなどの組み込みが解決されなくなります。
import { defaultDirectiveVocabulary } from "@takazudo/zudo-doc/directive-vocabulary-defaults";
export default defineConfig(
zudoDoc({
directives: {
...defaultDirectiveVocabulary,
callout: "Callout",
},
}),
);コンポーネント登録を含む完全なレシピはDirectives Registryを参照してください。
tagVocabularyEntries
タグ語彙のエントリ配列（ブールの tagVocabulary ゲートとは別物）。ルートコンテキスト仮想モジュールに通され、ガバナンス対応デフォルトスキーマビルダーが参照します。
型: readonly PresetTagVocabularyEntry[] · デフォルト: []
Warning
tagVocabulary（boolean ゲート）と tagVocabularyEntries（エントリ配列）を混同しないでください。これらは別のフィールドです — ゲートは語彙を参照するかどうかを決め、エントリは何を参照するかです。
シェルのパススルーフィールド
これらはホスト所有の ZfbConfig シェルフィールドで、Settings の一部ではありません。
port
dev/preview サーバーのポート。
デフォルト: 4321
adapter
デプロイターゲットのアダプターパッケージ名（例 "@takazudo/zfb-adapter-cloudflare"）。純粋な静的ビルドなら省略。
デフォルト: undefined（純粋な静的ビルド）
bundle
zfb バンドラーオプション（exclude / mainFields / external）。設定時にそのまま渡されます。
デフォルト: undefined
リファレンスとしての拡張プロジェクト
このショーケース自身の zfb.config.ts が標準的な「拡張プロジェクト」の例です — 型付き settings オブジェクトをスプレッドし、真にショーケース固有のデータブロック（タグ語彙、カスタム翻訳）をエスケープハッチフィールド経由で渡し、そしてシェルフィールド（port、adapter、bundle）を足します:
export default defineConfig(
zudoDoc({
...settings,
tagVocabularyEntries: tagVocabulary,
translations,
chromeBindingsModule: "./src/chrome-bindings.tsx",
port: 4321,
adapter: "@takazudo/zfb-adapter-cloudflare",
bundle: { exclude: ["e2e/fixtures/**"] },
}),
);最小プロジェクトにはそれらは一切不要です — 変更する少数のフィールドだけで済みます。