設定

唯一の 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 を返します — あなたは何もスプレッドしません。

ホームページ

home

/ と /ja/ などのロケール別ホームに適用するレイアウトと、省略可能な Markdown 紹介文の設定です。

デフォルト: { wide: false, introMarkdown: "", sitemapHeading: "" }

短い説明と既存のメタデータ用途には siteDescription を使い、ロケール別の短い説明は locales.<code>.description で上書きします。長い紹介文には introMarkdown を使います。メタデータや短い説明を置き換える設定ではありません。homeExtras / extras はスラッシュ区切りのリンク行にナビゲーションを追加するためのもので、紹介文用のスロットではありません。

Markdown 中心の例

zfb.config.ts を編集します。scaffold のルートページはパッケージを再エクスポートする1行のままで構いません。紹介文と見出しはシリアライズ可能な文字列なので、設定エディターでコールバックや実行可能な JavaScript を使わず保存できます。新規 scaffold の紹介文は空で、このショーケースの例文は新しいプロジェクトにコピーされません。

import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
    siteDescription: "A short guide to our project.",
    home: {
      wide: false,
      introMarkdown: `## Start here

Learn the **essentials**, then explore the reference.

- [Getting started](docs/getting-started/)
- [Configuration](docs/guides/configuration/)

> [!TIP]
> Keep the introduction focused on your readers' first steps.`,
      sitemapHeading: "Browse the guides",
    },
    locales: {
      ja: {
        label: "JA",
        dir: "src/content/docs-ja",
        description: "プロジェクトの使い方をまとめたガイド。",
        introMarkdown: `## はじめに

**基本的な使い方**を学んでから、リファレンスへ進めます。

- [はじめに](docs/getting-started/)
- [設定](docs/guides/configuration/)

> [!TIP]
> 読者が最初に必要とする情報に絞って紹介しましょう。`,
        sitemapHeading: "ガイドを探す",
      },
    },
  }),
);

ロケールの優先順位と紹介文なしの例

locales.<code>.introMarkdown と sitemapHeading は、定義するとそれぞれ対応する home の値を上書きします。ロケールのフィールドを省略すると home の値を継承します。紹介文に明示的な空文字列を指定するとフォールバックを無効化し、空白だけの場合も何も表示しません。これらはロケールの短い description とは独立しています。

解決後の sitemapHeading が空欄なら、英語は「Explore the documentation」、日本語は「ドキュメントを探す」という翻訳済みのデフォルトに戻ります。見出しを非表示にはしません。共通の見出しを変更していても、ロケールの見出しが空欄ならそのロケールのデフォルトに戻ります。

長い紹介文を表示しないホームには次の設定を使います。ロゴ、タイトル、短い説明、ナビゲーションは残り、紹介文のラッパーと上側の区切り線は表示されません。独立したサイトマップ H2 の前には区切り線が1本だけ表示されます。短い説明も非表示にするには、siteDescription と各ロケールの description を別途空にします。

home: { introMarkdown: "", sitemapHeading: "" },
locales: {
  ja: {
    label: "JA",
    dir: "src/content/docs-ja",
    introMarkdown: "",
    sitemapHeading: "",
  },
},

対応 Markdown と安全性の制限

紹介文には標準の Markdown/GFM パイプラインと、見出し以外の共通タイポグラフィを使用します。ただし、このフィールドには次の制限があります。詳細ページの例は Markdown 機能 を参照してください。そこで紹介する実行可能な MDX コンポーネントは、この文字列では使えません。

不正なソース、安全でない URL、未対応の生成マークアップは home.introMarkdown の診断とともにビルドを失敗させます。空でない紹介文にはサーバー/ビルド側レンダラーの peer 依存 @takazudo/zfb-md-wasm が必要です。空の紹介文では読み込みません。

リンクと画像

ソースファイルへのリンクではなく、ホームページからの URL を記述します。MDX 文書内のリンクと異なり、.md と .mdx の拡張子は書き換えません。相対 URL は末尾スラッシュ付きの現在のロケールのホームを基準に解決します。たとえばベースが /manual/ の日本語ホームでは、docs/getting-started/ は /manual/ja/docs/getting-started/、/docs/getting-started/ は /manual/docs/getting-started/ になります。ルート相対 URL にはベースを一度だけ付加し、明示的なロケール接頭辞を維持します。共通のルートアセットには /img/logo.svg を使います。img/logo.svg は現在のロケールのディレクトリを指します。

HTTP/HTTPS のリンクと画像に対応し、リンクは mailto: と tel: も使えます。フラグメントは維持し、パス内の空白はエンコードします。.. は通常の URL 解決に従うため、ベースの外へ移動する場合があります。プロトコル相対 URL、data:、javascript:、vbscript:、制御文字、バックスラッシュは拒否します。

コンパクトなレイアウトと見出し

サイトの識別情報と紹介文は、中央揃えの固定 最大幅 60rem（標準のルート文字サイズ 16px で 960 CSS px）を共有します。利用可能な幅に収まり、文字サイズの変更にも追従します。紹介文の幅を変える設定はありません。ロゴは 320 CSS px、縦横比 1200:630、最大幅 100% を維持します。デスクトップではロゴの右に左揃えの識別情報を配置し、モバイルでは縦に積んで中央揃えにします。紹介文は左揃えのままで、長いタイトル、短い説明、リンクは折り返します。

紹介文がある場合は、余白付きの文章をコンテンツ全幅の区切り線で挟み、その後に独立したサイトマップ H2 と既存のドキュメントツリーを表示します。タグが有効な場合は、同じ区切り線をタグ見出しの前にも表示します。区切り線は内側の 60rem 制限ではなく、外側のページコンテナに従います。home.wide: true は引き続き外側のコンテナとカテゴリ一覧を広げ、従来の動作を維持します。

詳細ページの見出しと異なり、コンパクトな見出しは枠線、グラデーション、ハッシュ装飾のない太字です。Markdown の H1 は H2 に変換してページの H1 を1つに保ち、紹介文の見出しはドキュメント TOC に入りません。H2 はサイトマップ見出しやタグ見出しと同じホーム用セクション見出しスタイル（既定で text-title の 1.4rem、行送り 1.25。テーマパックの H2 罫線・番号・バー装飾は除去）を共有し、H3 は 1.125rem、H4 は 1rem、H5/H6 は 0.9375rem、本文は 1rem/1.75 です。通常の要素間隔は 1rem、見出しに隣接する間隔は 0.5rem、セクション間隔は H2 が 1.75rem、H3 が 1.5rem、それより下は 1.25rem です。最初の子要素の上側には間隔を設けません。

siteTreeNavIgnore

/ や /ja のようなロケール接頭辞付きホームページにあるパッケージ所有のカテゴリグリッド、および <SiteTreeNav /> / <SiteTreeNavDemo /> MDX タグから非表示にするトップレベルカテゴリのスラッグです。ヘッダーナビ、サイドバー、検索、サイトマップには影響しません。

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
    siteTreeNavIgnore: ["inbox", "develop"],
  }),
);

このショーケース固有の用途のため、以前はパッケージが ["inbox", "develop"] をハードコードしていました。現在のパッケージデフォルトは [] です。サイトでカテゴリを非表示にしたい場合はこのフィールドを設定してください。

型: string[] · デフォルト: []

アイデンティティと URL

siteName

ヘッダーとメタデータに表示されるサイト名。ページタイトルは {page title} | {siteName} としてレンダリングされます。ほぼ必ず設定する唯一のフィールドです。

デフォルト: "Docs"

siteDescription

メタデータ（<meta name="description">、llms.txt）で使われるサイト説明。

デフォルト: ""

logo

ホームのヒーローに表示するロゴ。"auto"（デフォルト）は siteName をシードにした決定論的な生成 SVG — フレーム付きの「装飾プレート」マーク — を描画します。ライト/ダークに自動追従するため、新規プロジェクトでもアセットなしで見栄えのするヒーローになります。パス文字列（例 "/img/logo.svg"）を指定すると自前のアセットをテーマ適応の CSS マスクとして描画し、false でロゴブロック自体を非表示にします。

npx zudo-doc eject logo を実行すると、生成されたマークを実ファイルとして実体化できます — public/img/logo.svg を書き出し、このフィールドを "/img/logo.svg" に切り替えます。これにより、リクエスト時に生成されるデフォルトの代わりに、編集・差し替え・別用途（OGP など）での再利用ができる実ファイルを所有できます。CLI フラグについてはカスタマイズ → 第5段を参照してください。

logo: "" を指定すると、空パスの CSS マスクを黙って描画する代わりに、設定解決の時点で TypeError がスローされます — ロゴを非表示にしたい場合は false を、デフォルトのままでよければフィールド自体を省略してください。

デフォルト: "auto"

favicon

各ページの <head> に出力される <link rel="icon"> のセット。省略すると、create-zudo-doc が新規プロジェクトの public/ に同梱する 4 ファイル構成 — favicon.svg、favicon.ico（sizes="any"）、favicon-32x32.png、favicon-16x16.png — がこの順で出力されます。

型: string | FaviconConfig | false · デフォルト: undefined（上記 4 リンクのセット）

空文字列は出力されず、拒否されます。 HTML の仕様では空の href は「現在のドキュメント自身」に解決されるため、favicon: "" を許すと全ページが自分自身の HTML を favicon として黙ってフェッチしてしまいます — 無駄なリクエストであり、タブアイコンとしても壊れています。zudoDoc({ favicon: "" }) はその代わりにフィールド名を含む TypeError をスローします。favicon のリンクを出したくない場合は false を、デフォルトの 4 リンクセットでよければフィールドを省略してください。この拒否は FaviconConfig の空文字列スロット（例: favicon: { ico: "" }）にも同様に適用され、エラーは該当スロット名（favicon.ico）を含みます。空のオブジェクト（favicon: {}、スロットなし）はこの対象外で、これまでどおり何も出力しません。拒否されるのは厳密に空文字列 "" のみで、" " のような空白のみの値はそのまま通過します。

デフォルトはあくまで規約であり、ファイルの存在チェックではありません。 実ファイルの有無にかかわらず 4 本のリンクを出力するため、public/ に favicon.ico を置いていないプロジェクトでも全ページに <link rel="icon" href="/favicon.ico" sizes="any"> が出力され、訪問者のブラウザーコンソールにはもれなく 404 が記録されます。これを避けるには、実際に用意してあるスロットだけをオブジェクト形式で指定します。

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
    // No favicon.ico in public/, so no ico link — and no console 404.
    favicon: {
      svg: "/favicon.svg",
      png32: "/favicon-32x32.png",
      png16: "/favicon-16x16.png",
    },
  }),
);

FaviconConfig は { svg?: string; png32?: string; png16?: string; ico?: string } です。すべてのキーが任意で、オブジェクト内での記述順は出力に影響しません（出力順は固定です）。{} は何も出力せず、false と同じ結果になります。

素の文字列を渡すとセットはリンク 1 本に縮退し、type は拡張子から推論されます（.svg、.png、.ico、.jpg / .jpeg、.gif、.webp、.avif）。それ以外の拡張子では type を省略し、ブラウザーの判定に委ねます。推論時に ?query や #hash は無視されるため、"/icon.svg?v=2" でも type="image/svg+xml" が付きます。

favicon: "/icon.png", // one link, type="image/png"
favicon: false,       // no favicon links at all

favicon: "auto" はアセットファイルを一切必要としません。siteName から決定論的に生成した SVG favicon を、インライン data: URL のリンク 1 本として出力します。グリフのシードは logo: "auto" と同じなので、ヒーローのロゴとブラウザータブのアイコンには同じマークが表示されます。ただし favicon 側は正方形・不透明で、パレットはライト固定です。タブのアイコンは、CSS マスクで描画されるヒーローロゴのようにページのカラーモードへ追従できないためです。

/ で始まる href の値には、設定した base が前置されます。サブパスにデプロイした場合、"/favicon.svg" は /pj/my-site/favicon.svg に解決されます。それ以外の値 — https://… の絶対 URL や data: URL — はそのまま出力されます。

siteUrl

サイトマップ / canonical / og:url のための正規サイトオリジン（例 "https://example.com"）。空 = 未設定。

デフォルト: ""

base

すべての絶対アセット URL の前にマウントされる公開 URL サブパスプレフィックス（例 "/pj/my-site/"）。"/" = ルートマウント。すべての内部リンク（サイドバー、ナビ、prev/next、検索）は自動的にプレフィックスされます。

デフォルト: "/"

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 }

sitemap

サイトマップルートを出力します。

デフォルト: false

サイトマップが必要なら sitemap: true を明示的に設定してください。 デフォルトの false では /sitemap.xml ルートそのものが出力されず、この URL は 404 になります。siteUrl を設定しただけでは有効になりません。canonical や og:url のためだけに siteUrl を設定するのはごく普通の構成なので、そこから意図を推測することはせず、ビルド時に警告も出しません。この取り決めが明文化されているのは、このリファレンスです。

何も配信しないのは意図的な設計です。よく知られた URL に置かれた空の <urlset> は中立的なプレースホルダーではなく、「このサイトにはインデックス可能な URL が 1 つもない」とクローラーに積極的に宣言するものであり、URL が単に存在しない状態よりも悪い結果になります。生成される robots.txt はこの状態ですでに Sitemap: 行を省いているため、両者は矛盾することなく一致するようになりました。以前のバージョンは空の <urlset> を出力していましたが、現在は出力しません。

この判定はパッケージのルート注入（packageOwnedRoutes、デフォルトで有効）側で行われます。自前で pages/sitemap.xml.tsx を用意しているプロジェクトはその外側にあり、そのページが返すものがそのまま使われます。sitemap が false のままそのページがパッケージのエントリポイントを再エクスポートしている場合は、ビルドが警告を出したうえで空の <urlset> を書き出します。

metaTags と sitemap を組み合わせたソーシャル共有・検索インデックス設定の全体像は SEO ガイド も参照してください。

onBrokenMarkdownLinks

.md/.mdx リンクが解決できないときの挙動: "warn" はログして続行、"error" はビルドを失敗、"ignore" は無音。

型: "warn" | "error" | "ignore" · デフォルト: "warn"

この設定は、ビルド後のHTMLにある生の<img src>の存在確認にも適用されます。"error"は問題を報告してビルドを失敗させ、"warn"は警告して続行し、"ignore"は検査自体を省略します。

検査対象は/で始まるサイト内の絶対パスです。クエリとフラグメントを除去し、URLエンコードを復号して、ビルド出力内のファイルを確認します。base: "/manual/"なら/manual/img/logo.svgはdist/img/logo.svgに対応します。baseの外を指すパス、存在しないファイル、出力ディレクトリの外へ抜けるパスは問題として報告されます。

外部URL、//で始まるURL、data:などのスキーム付きURL、相対パスは対象外です。コメント、スクリプト内の文字列、エスケープされたコード例も画像として扱いません。srcsetは検査しません。

カラー

colorScheme

アクティブなカラースキーム名（colorSchemes に存在する必要があります）。バンドルされる2つのスキームは Default Light と Default Dark です。

デフォルト: "Default Dark"

colorMode

ライト/ダークモードの配線、または単一固定スキームなら false。

デフォルト: { defaultMode: "dark", lightScheme: "Default Light", darkScheme: "Default Dark", respectPrefersColorScheme: true }

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/content/docs"

entryDocSlug

バージョン一覧ページが「最新ドキュメント」へのエントリーポイント（および過去の各バージョンのドキュメントリンク）として使用するドキュメントページのルートスラッグ。先頭・末尾にスラッシュを含まない（例："getting-started"、"overview/getting-started"）。実行時のバリデーションは行われず、無効なスラッグは単に404になる。

デフォルト: "getting-started"

dateFormat

日付の表示形式。"locale" は組み込みの Intl による表示をそのまま使い、それ以外の文字列はトークンパターンとして解釈されます。

型: DateFormatSetting · デフォルト: "locale"

zudo-doc が表示する日付には 5 つの形があり、この設定は呼び出し箇所ごとではなく、その形ごと（以下「ロール」）に指定します。ページャーの日付だけを見出しの日付と別の形式にしたいという要望はまずありませんが、カードの短い日付スタンプと本文の完全な日付行は、そもそも別物だからです。

numericMonthDay のデフォルトが意図的にロケール非依存になっているのは、これが文章ではなく桁の揃った短いスタンプだからです。どのロケールでも 08-22 になります。パターンを与えれば他のロールと同じように整形されます。

文字列だけを渡すと full しか変わらない

この設定で唯一つまずきやすいのがここです。文字列単体は { full: "…" } の短縮形なので、h1 直下の日付行やページャーなど full を使う場所だけが変わり、カードの日付スタンプ・年月見出し・サイドバーの行はそのまま残ります。

dateFormat: "YYYY/MM/DD",

これらも変えたい場合は、対応するロールを明示してください。

ロールとロケール別の上書き

オブジェクト形式では 5 つのロールキーに加えて、ロケールコードをキーとする locales を指定できます。locales の値も同じ 5 つのキーを取ります。

dateFormat: {
  full: "MM/DD/YYYY",
  yearMonth: "MM/YYYY",
  locales: {
    ja: { full: "YYYY年M月D日" },
  },
},

解決順序はロールごとに次のとおりです。

1. locales[locale][role] — ロケール別の上書き

2. [role] — トップレベルのロール

3. "locale" — 組み込みの Intl 表示

多言語サイトでオブジェクト形式を使う理由がこのロケール別上書きです。Aug 22, 2026 も 2026年8月22日 もそれぞれのロケールでは正しく、1 つのパターンで両方を賄うことはできません。国際化（i18n）も参照してください。

サポートするトークン

マッチングの挙動で押さえておきたい点は次のとおりです。

• トークン以外の文字はそのまま出力されるので、/、-、.、空白、年 月 日 にエスケープは不要です。

• 同じ位置では長いトークンが優先されます。YYYY は YY に、MMMM は MMM・MM・M に勝ちます。

• 置換後の月名は再走査されないため、March や May の M が壊れることはありません。

• 解釈できない並びはビルドを失敗させずにそのまま出力されます。YYYYY は年に続けてリテラルの Y、dddd は dddd のままです。

• 角括弧はネストできず、最初の ] でエスケープが閉じます。閉じない [ はリテラルとして出力され、後続のトークンは通常どおり解決されます。

• MMM と MMMM が月名をローカライズできるのは en・ja・de だけで、それ以外のロケールは英語の月名になります。ロケールごとの日付形式を参照してください。

記述例

文字列単体を渡した場合、全ロケールで full ロールだけが変わります。h1 直下の日付行とページャーは 2026/08/22 になり、カードの日付スタンプ・年月見出し・サイドバーの行は変わりません。

export default defineConfig(
  zudoDoc({
    dateFormat: "YYYY/MM/DD",
  }),
);

2 つのロールを全ロケールで指定した場合、full は 08/22/2026、yearMonth は 08/2026 になります。monthDay・year・numericMonthDay は "locale" のままです。

export default defineConfig(
  zudoDoc({
    dateFormat: {
      full: "MM/DD/YYYY",
      yearMonth: "MM/YYYY",
    },
  }),
);

ロケール別に指定した場合、英語ページは Aug 22, 2026、日本語ページは 2026年8月22日 になります。yearMonth は ja でのみ上書きしているので、英語はデフォルトの 2026 August、日本語は 2026年8月 です。

export default defineConfig(
  zudoDoc({
    dateFormat: {
      full: "MMM D, YYYY",
      locales: {
        ja: { full: "YYYY年M月D日", yearMonth: "YYYY年M月" },
      },
    },
  }),
);

オブジェクトを渡すとデフォルトを丸ごと置き換える

zudoDoc() が指定値をパッケージのデフォルトにマージするのはトップレベルだけです。したがって dateFormat にオブジェクトを渡すと、デフォルトの "locale" は深くマージされずそのまま置き換わります。ただしこれが問題になることはありません。省略したロールにはリゾルバーが "locale" を補うので、結果はデフォルトが意味していたものと同じだからです。

影響しないもの

dateFormat はあくまで表示の設定です。フロントマターの記述形式である YYYY-MM-DD、<time> 要素の機械可読な datetime 属性、サイトマップの lastmod、年・年月見出しの裏側にあるグループキーは変わりません。いずれも ISO のままです。

defaultLocale

デフォルトロケールコード（プレフィックスなしのルート）。

デフォルト: "en"

locales

追加ロケール: コード → { label, dir, description?, introMarkdown?, sitemapHeading? }。それぞれが /<code>/docs/… ルートツリーと docs-<code> コレクションになります。マップの順序が維持され、言語切り替えは設定したすべての label をその順序で表示するため、JP や JA に固定されません。

デフォルト: {}

locales: {
  ja: {
    label: "JA",
    dir: "src/content/docs-ja",
    description: "プロジェクトの使い方をまとめたドキュメント。",
  },
  de: { label: "DE", dir: "src/content/docs-de" },
},

descriptionは、そのロケールのホームページのヒーローに表示する説明文です。文字列で指定でき、省略するとsettings.siteDescriptionが使われます。空文字列（""）を指定した場合は、説明文を空欄にできます。settings.localesに登録するのはデフォルト以外のロケールだけなので、デフォルトロケールでは常にsettings.siteDescriptionが使われ、ロケール別の上書きはできません。

現時点では、この設定が反映されるのはホームページのヒーローの説明文だけです。llms.txtはどのロケールでも共通のsiteDescriptionを使い、ホームページには引き続き<meta name="description">が出力されません。

ロケールコードは URL セグメントとディレクトリのサフィックスに使われます。小文字でパス安全な値にしてください。重複、プライマリの defaultLocale、パス区切り文字、トラバーサル要素は、create-zudo-doc がファイルを書き込む前に拒否します。生成される ja ツリーは日本語の文章、それ以外の任意のロケールツリーは翻訳用の英語プレースホルダー文章から始まります。

defaultLocaleOnlyPrefixes

デフォルトロケールのみで提供されるルートプレフィックス（ロケールプレフィックスされない）。言語切り替えは該当ページでこれらを省略します。

デフォルト: []

デフォルトロケール限定プレフィックスを参照してください。

versions

ドキュメントのバージョン、または単一（バージョンなし）のドキュメントセットなら false。各バージョンセクションは /v/{slug}/docs/ で提供されます。

型: VersionConfig[] | false · デフォルト: false

バージョニングガイドを参照してください。

mermaid

マークダウンでの mermaid ダイアグラムレンダリングを有効化します。

デフォルト: true

transclude

:::include{file="…"} による transclude を有効化します。zudo-doc は、この boolean 値が有効なとき、オブジェクト型である zfb の markdown.features.transclude: {} へ変換します。パッケージ所有の Markdown 機能ブロックを置き換えず、ここで設定してください。

export default defineConfig(
  zudoDoc({
    transclude: true,
  }),
);

型: boolean · デフォルト: false

ディレクティブ構文、ファイルシステム上の制約、ビルドを失敗させるエラーについては Transclude を参照してください。

math

KaTeX 数式レンダリング（$…$、$$…$$、フェンス math）を有効化します。

デフォルト: false

math: true にはオプショナルピア依存の katex のインストールが必要です（pnpm add katex）— create-zudo-doc は自動で追加せず、新規 scaffold の package.json には含まれません。katex は @takazudo/zudo-doc のオプショナルピアです。インストールしなくてもビルドは通りますが、実行時に <MathBlock> のレンダリングが例外を投げます。コンポーネントについては数式を参照してください。docHistory の Compare ビューも diff について同様の契約を持ちます — 下記のdocHistoryを参照してください。

cjkFriendly

zfb の CJK フレンドリーな改行 / 強調処理を有効化します。

デフォルト: false

タグ

tagVocabulary と tagGovernance は直交しています — 一方はランタイムのゲート、もう一方は強制レベルです。語彙のエントリは tagVocabularyEntries エスケープハッチで別途供給します。

docTags

/docs/tags + /docs/tags/[tag] タグインデックスルートを有効化します。

デフォルト: 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

この機能を有効にしてスキャフォールドしたプロジェクトでは、パネルは追加設定なしで動作します — そのときにオプショナルピアの @takazudo/zdtp がインストールされ、@import "@takazudo/zdtp/styles.css"; の行も追加されるためです。パネルなしでスキャフォールドしたプロジェクトで有効化する場合は、この 2 つを手作業で行う必要があります。行わないと、パネルの遅延 import("@takazudo/zdtp") が実行時に失敗し、警告がログに出るだけになります。完全にカスタマイズするには、designTokenPanelConfigModule をホストモジュールに向けます — ホストクロームバインディングを参照してください。

sidebarResizer

ドラッグ可能なサイドバーリサイザーを有効化します。

デフォルト: false

sidebarToggle

デスクトップのサイドバー折りたたみトグルを有効化します。

デフォルト: false

tocToggle

デスクトップの目次折りたたみトグルを有効化します。xl 幅（1280px 以上）の画面で、ビューポート右端にシェブロンボタンが固定表示されます。

デフォルト: false

目次を畳むと、空いた幅はそのままコンテンツ側に渡ります。ここがこの機能の狙いで、横に広いテーブルや長い行のコードブロックが、折り返しや横スクロールなしで読めるようになります。読者が選んだ状態は保存されるため、ページを移動しても、次に訪れたときも維持されます。

このトグルが効くのはパッケージ標準の目次だけです。chromeBindingsModule で Toc スロットを差し替えている場合、独自のコンポーネントはそのまま描画され、トグルも表示されません。ホストクロームバインディングを参照してください。

imageEnlarge

コンテンツ画像のクリック拡大を有効化します。

デフォルト: false

assetViewer

public/<assetViewerDir>/ 配下で対象となる各ファイルに、デフォルトロケールの閲覧ページを生成します。同時に、MDX でアセットリンク、カード、コード抜粋、画像キャプションのリンクを利用できるようにします。

デフォルト: false

ディレクトリ構成、閲覧ページの挙動、MDX からの参照方法は アセットビューアーを参照してください。

assetViewerDir

ビューアーで扱うファイルを置く public/ 配下のディレクトリを指定します。同じ値が、公開ファイルそのものを返す URL のプレフィックスになります。

デフォルト: "assets"

安全な相対 URL パスを指定し、assetViewerRoutePrefix とは異なる値にする必要があります。

assetViewerRoutePrefix

生成される閲覧ページの URL プレフィックスを指定します。

デフォルト: "files"

デフォルト設定では、public/assets/guide.pdf の公開 URL は /assets/guide.pdf、閲覧ページは /files/guide.pdf/ になります。

assetViewerExclude

アセットディレクトリからの相対パスに glob を適用し、閲覧ページの生成対象から除外します。元のファイルは public/ に残ります。

型: string[] · デフォルト: []

たとえば ["**/*.map", "drafts/**"] を指定すると、ソースマップとアセットディレクトリ内の drafts/ 配下を除外できます。

assetViewerIndex

アセットビューアーが有効なとき、/<assetViewerRoutePrefix>/ にアセット一覧ページを生成します。

デフォルト: false

一覧の挙動とヘッダーナビへの追加方法は アセットビューアーを参照してください。

assetViewerIndexing

アセット閲覧ページを、検索インデックス、llms.txt、サイトマップへ個別に追加します。assetViewer: true が前提となり、ビューアーが無効な場合はインデックス用のサブキーを設定しても何も起こりません。

型: false | { search?: boolean; llmsTxt?: boolean; sitemap?: boolean } · デフォルト: false

一部のキーだけを持つオブジェクトを指定した場合も含め、各サブキーは明示的に true を指定しない限り無効です。search は、asset: プレフィックス付きの ID でアセットページを search-index.json に追加します。llmsTxt は、llms.txt に ## Files セクションを追加し、llms-full.txt にアセットページを追記します。テキストとして扱えるアセットでは本文を最大 8 KB まで収録し、それを超える場合は末尾に切り詰めを明示するマーカーを付けます。バイナリアセットは本文を含まない 1 行のスタブとして掲載します。sitemap は /files/... のルートを追加します。

設定例はアセットビューアーを参照してください。このショーケースでは 3 つのサブキーをすべて有効にしています。

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

フロントマタープレビューリファレンスを参照してください。

docHistory

ページ単位の git 履歴（Created/Updated + ドロップダウン）を有効化します。dev では @takazudo/zudo-doc-history-server がポート 4322 で履歴を提供し、CI ではジェネレーターが静的 JSON を出力します。

デフォルト: false

履歴ドロップダウンの Compare ビューにはオプショナルピア依存の diff が必要です。ビルド自体には不要です。create-zudo-doc は docHistory が選択されたとき — 直接選択された場合と、docHistory を強制的に有効化する bodyFootUtilArea 経由の場合の両方で — package.json に diff を自動的に追加します。diff は @takazudo/zudo-doc のオプショナルピアなので、ジェネレーターを介さず zfb.config.ts で手動により docHistory を有効化したプロジェクトは、自分で pnpm add diff する必要があります。katex との対応する契約については上記のmathを参照してください。

ドキュメント履歴ガイドを参照してください。

docHistoryUi

履歴ボタンとDocHistoryアイランド、postBuildの履歴JSON生成、開発時の履歴プロキシを制御します。falseでも、docHistory: trueならpreBuildのメタデータマニフェストは生成されます。ソース表示リンクも維持されます。

型: boolean · デフォルト: true

zfb.config.tsを手動で編集して設定します。新しいCLIフラグはありません。環境変数との関係やCIジョブの整理についてはドキュメント履歴ガイドを参照してください。

docMetainfo

ドキュメントページに Created/Updated/Author メタブロックを表示します（ビルド時に git 履歴から抽出）。

デフォルト: false

bindingsモジュールはdocHistoryMetaを提供する必要があります。デフォルトの{}データスロットでは、描画するメタデータブロックがありません。組み合わせるdocHistory設定についてはドキュメント履歴ガイドを参照してください。

docMetainfoFields

メタデータブロックに表示する項目を選びます。docMetainfo: trueと、データを提供するdocHistoryMetaバインディングが必要です。

型: Array<"created" | "updated" | "author"> · デフォルト: ["created", "updated", "author"]

省略すると全項目が有効です。表示順はCreated、Updated、Authorで、配列の順番では変わりません。Createdも表示する場合、日付書式で整形した表示値がCreatedと同じUpdatedは省略されます（日付書式には時刻も含められます）。["updated"]なら表示値が同じでもUpdatedを表示します。[]ではメタデータブロックを描画しません。

docMetainfo: true,
docMetainfoFields: ["updated"],

zfb.config.tsを手動で編集して設定します。新しいCLIフラグはありません。表示項目を減らしても履歴データの生成は停止しません。

bodyFootUtilArea

body-foot ユーティリティエリア（doc-history / view-source）、または無効化するなら false。

型: BodyFootUtilAreaConfig | false · デフォルト: false

htmlPreview

グローバルな HTML プレビューサンドボックス設定、または各 <HtmlPreview> iframe へのグローバル注入を無効化するなら undefined。

型: HtmlPreviewConfig | undefined · デフォルト: undefined

footer

フッター設定（リンクカラム / コピーライト / タグリスト）、またはフッターなしなら false。

型: FooterConfig | false · デフォルト: false

各 FooterLinkColumn は title、items（{ label, href }[]）、および任意のロケール別上書きを持ちます。

headerNav

ヘッダーの主要ナビゲーション項目。

デフォルト: []

headerNav: [
  { label: "Guides", path: "/docs/guides", categoryMatch: "guides" },
  { label: "Reference", path: "/docs/reference", categoryMatch: "reference" },
],

ナビゲーションの構成方法を参照してください。

headerRightItems

ヘッダー右側の項目（トグル、スイッチャー、リンク）を順に。

デフォルト: [{ type: "component", component: "theme-toggle" }]

AI アシスタント

aiAssistant

AI チャットアシスタントルート（/api/ai-chat、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/ai-chat を固定の「無効」応答でショートサーキットします（API キー、KV、Durable Object、レートリミッター、provider fetchに触れません）。ライブの Claude 対応チャットを有効化するには false にします。

デフォルト: false

aiChatAllowedOrigins

デモモードでないときの /api/ai-chat の許可 CORS オリジン。空 = すべてのクロスオリジンブラウザリクエストをブロック。

デフォルト: []

aiChatGlobalDailyLimit

/api/ai-chatの全IPを合算したUTC日ごとの正確なAnthropic fetch許可上限です。falseなら 正確な上限を無効化します。provider/network障害でも許可枠は返却しません。

型: number | false · デフォルト: false

生成とインテグレーション

llmsTxt

ドキュメントを要約する llms.txt ルートを出力します。

デフォルト: false

llms.txtを参照してください。

changelogs

Changelog 生成設定、または無効化するなら false。

デフォルト: false

マルチパッケージプロジェクトでは、パッケージごとに1つの項目を追加します。各sourceDirには、トップレベルの変更履歴ランディングディレクトリではなく、index.mdx以外のリリース別MDXファイルを含むパッケージ固有のディレクトリを指定する必要があります：

changelogs: [
  {
    sourceDir: "src/content/docs/changelog/core",
    outputFile: "packages/core/CHANGELOG.md",
    packageName: "@acme/core",
  },
  {
    sourceDir: "src/content/docs/changelog/cli",
    outputFile: "packages/cli/CHANGELOG.md",
    packageName: "@acme/cli",
  },
],

Changelog ガイドを参照してください。

claudeResources

Claude リソースの取り込み設定、または無効化するなら false。

型: { claudeDir; projectRoot?; scanRoot? } | false · デフォルト: false

claudeResources: { claudeDir: ".claude" },

Claude Resources ガイドを参照してください。

codexResources

Codexリソースの取り込み設定、または無効化するならfalse。

型: { codexDir; projectRoot?; scanRoot? } | false · デフォルト: false

codexResources: { codexDir: ".codex" },

Codexリソースガイドを参照してください。

ルーティングの継ぎ目

packageOwnedRoutes

ビルド時のパッケージ所有ルート注入。true のとき、ドキュメントルートはパッケージから注入されます（プロジェクト側の pages/*.tsx レイアウトスタブは不要）。プロジェクトが自前のドキュメントルートスタブを出荷する場合のみ false にします。

デフォルト: true

chromeBindingsModule

defineChromeBindings（@takazudo/zudo-doc/chrome-bindings）で構築した chromeBindings オブジェクトをエクスポートするホストモジュールへのプロジェクトルート相対パス（packageOwnedRoutes がオンのときのみ消費）。注入されたクロームシムをパッケージデフォルトのスタブのままにするなら省略。

デフォルト: undefined

ホストクロームバインディングを参照してください。

エスケープハッチフィールド

これらは非シリアライズ可能 / データデフォルトを上書きします。JSON シリアライズではなくインポートグラフを通じて移動するため、関数、Zod 型、コンポーネントマップを運べます。

buildDocsSchema

デフォルトのドキュメントフロントマター Zod スキーマビルダーを完全に置き換えます。省略時、zudoDoc() はパッケージデフォルト（@takazudo/zudo-doc/docs-schema）を構築します（ガバナンス対応。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

import { defaultDirectiveVocabulary } from "@takazudo/zudo-doc/directive-vocabulary-defaults";

export default defineConfig(
  zudoDoc({
    directives: {
      ...defaultDirectiveVocabulary,
      callout: "Callout",
    },
  }),
);

コンポーネント登録を含む完全なレシピはDirectives Registryを参照してください。

tagVocabularyEntries

タグ語彙のエントリ配列（ブールの tagVocabulary ゲートとは別物）。ルートコンテキスト仮想モジュールに通され、ガバナンス対応デフォルトスキーマビルダーが参照します。

型: readonly PresetTagVocabularyEntry[] · デフォルト: []

シェルのパススルーフィールド

これらはホスト所有の 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/**"] },
  }),
);

最小プロジェクトにはそれらは一切不要です — 変更する少数のフィールドだけで済みます。