zudo-doc プロジェクトは1つのファイルで設定します。ルートの **`zfb.config.ts`** です。変更したいフィールドを付けて `zudoDoc()` を呼び出し、それ以外の設定はすべて文書化されたデフォルトにフォールバックします。 ```ts title="zfb.config.ts" 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`** を返します — あなたは何もスプレッドしません。 [Dynamic content unavailable in text export] `ZudoDocConfig` 型がこのリファレンスの唯一の情報源です。すべてのフィールドは `@default` の JSDoc 注釈を持ち、IDE のホバーで表示されます。以下の表はそのデフォルトをそのまま反映しています。このページと型が食い違う場合は、型が正しいです。 [Dynamic content unavailable in text export] ここでのデフォルトは、新規の `create-zudo-doc` プロジェクトが継承する**パッケージデフォルト**です。このショーケースはそれらのフィールドを明示的に渡すことで、はるかに多くを有効化しています（ほとんどの機能オン、i18n、フルのヘッダーナビ）。ショーケースのリッチな設定をデフォルトのベースラインとして読まないでください。 ## ホームページ ### home `/` と `/ja/` などのロケール別ホームに適用するレイアウトと、省略可能な Markdown 紹介文の設定です。 デフォルト: `{ wide: false, introMarkdown: "", sitemapHeading: "" }` | フィールド | 型 | 用途 | |---|---|---| | `wide` | `boolean` | カテゴリ一覧用に外側のページコンテナを広げます。デフォルトは `false`。 | | `introMarkdown` | `string` | ロゴ、タイトル、短い説明、ナビゲーションの下に表示する紹介文。 | | `sitemapHeading` | `string` | 既存のドキュメントツリーの上に表示するプレーンテキストの見出し。空欄なら翻訳済みのデフォルトを使用。 | 短い説明と既存のメタデータ用途には `siteDescription` を使い、ロケール別の短い説明は `locales..description` で上書きします。長い紹介文には `introMarkdown` を使います。メタデータや短い説明を置き換える設定ではありません。[homeExtras / extras](https://zudo-doc.takazudomodular.com/ja/docs/reference/host-chrome-bindings) はスラッシュ区切りのリンク行にナビゲーションを追加するためのもので、紹介文用のスロットではありません。 #### Markdown 中心の例 `zfb.config.ts` を編集します。scaffold のルートページはパッケージを再エクスポートする1行のままで構いません。紹介文と見出しはシリアライズ可能な文字列なので、設定エディターでコールバックや実行可能な JavaScript を使わず保存できます。新規 scaffold の紹介文は空で、このショーケースの例文は新しいプロジェクトにコピーされません。 ```ts title="zfb.config.ts" 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..introMarkdown` と `sitemapHeading` は、定義するとそれぞれ対応する `home` の値を上書きします。ロケールのフィールドを省略すると `home` の値を継承します。紹介文に明示的な空文字列を指定するとフォールバックを無効化し、空白だけの場合も何も表示しません。これらはロケールの短い `description` とは独立しています。 解決後の `sitemapHeading` が空欄なら、英語は「Explore the documentation」、日本語は「ドキュメントを探す」という翻訳済みのデフォルトに戻ります。見出しを非表示にはしません。共通の見出しを変更していても、ロケールの見出しが空欄ならそのロケールのデフォルトに戻ります。 長い紹介文を表示しないホームには次の設定を使います。ロゴ、タイトル、短い説明、ナビゲーションは残り、紹介文のラッパーと上側の区切り線は表示されません。独立したサイトマップ H2 の前には区切り線が1本だけ表示されます。短い説明も非表示にするには、`siteDescription` と各ロケールの `description` を別途空にします。 ```ts home: { introMarkdown: "", sitemapHeading: "" }, locales: { ja: { label: "JA", dir: "src/content/docs-ja", introMarkdown: "", sitemapHeading: "", }, }, ``` #### 対応 Markdown と安全性の制限 紹介文には標準の Markdown/GFM パイプラインと、見出し以外の共通タイポグラフィを使用します。ただし、このフィールドには次の制限があります。詳細ページの例は [Markdown 機能](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features) を参照してください。そこで紹介する実行可能な MDX コンポーネントは、この文字列では使えません。 | 内容 | ホームページの紹介文での動作 | |---|---| | 段落、強調、太字、取り消し線、改行 | 対応。 | | 番号付き、番号なし、入れ子、タスクリスト | 対応。チェックボックスの checked/disabled 状態を保持。 | | リンク、参照リンク、画像 | 安全な URL に対応。画像はレスポンシブ。ファイルからの寸法取得やアセットビューアーへの変換は行いません。 | | 引用と GitHub アラート | 対応。`> [!TIP]` などの GitHub アラート記法を使います。 | | インラインコードとコードフェンス | 本番のセマンティックハイライトに対応。コード例は実行せず、幅の広いフェンスは内部でスクロール。 | | 表と水平線 | 対応。表の文字揃えを保持し、幅の広い表は内部でスクロール。 | | ルビ | 実行を伴わない `{base}^{reading}` 記法に対応。 | | Mermaid | `mermaid: true` では既存の Mermaid 初期化処理で図を表示し、無効時は通常のコードフェンスになります。 | | 数式 | `math: true` でもドル記号の記法はそのまま表示。JSX の `MathBlock` は使えません。 | | ディレクティブ、トランスクルージョン、ファイルのインクルード | 文書ページで有効でも拒否。紹介文には文書のソースパスがありません。 | | 生 HTML、JSX、MDX 式、import/export、YAML フロントマター | 診断付きで拒否し、実行しません。インラインコードやフェンス内では例として表示可能。通常の非 MDX の波括弧は文字列のままです。最初の段落の import/export 文は予約されています。 | | コードタブ、高度なフェンス拡張、見出しマーカー、読了時間/TOC エクスポート | 無効。通常のフェンスは使えますが、高度なメタデータでコンポーネント同等の表示は保証しません。 | 不正なソース、安全でない 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` のようなロケール接頭辞付きホームページにあるパッケージ所有のカテゴリグリッド、および `` / `` MDX タグから非表示にするトップレベルカテゴリのスラッグです。ヘッダーナビ、サイドバー、検索、サイトマップには影響しません。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ siteName: "My Docs", siteTreeNavIgnore: ["inbox", "develop"], }), ); ``` このショーケース固有の用途のため、以前はパッケージが `["inbox", "develop"]` をハードコードしていました。現在のパッケージデフォルトは `[]` です。サイトでカテゴリを非表示にしたい場合はこのフィールドを設定してください。 型: `string[]` · デフォルト: `[]` ### siteTreeNavSecondary `/` や `/ja` のようなロケール接頭辞付きホームページで、パッケージ所有のカテゴリグリッドから外し、その直下のコンパクトなセカンダリ行へ移すトップレベルカテゴリのスラッグです。指定したカテゴリはそれぞれ、ラベル付きの小さなシェブロンリンクとして表示されます。行内の並び順はグリッドのカテゴリ順ではなく、配列の順序に従います。ホームページから辿れるようにはしておきたいものの、主要な読み進めの導線とは競合させたくないシステム系のカテゴリに使います。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ siteName: "My Docs", siteTreeNavSecondary: ["changelog", "claude", "codex"], }), ); ``` - どのトップレベルカテゴリにも一致しないスラッグは無視されます。 - [`siteTreeNavIgnore`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%83%9B%E3%83%BC%E3%83%A0%E3%83%9A%E3%83%BC%E3%82%B8-sitetreenavignore) にも含まれるスラッグは完全に非表示になります。`siteTreeNavIgnore` が優先されます。 - 自身のページを持たないカテゴリ（[`category_no_page: true`](https://zudo-doc.takazudomodular.com/ja/docs/guides/frontmatter#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E8%A9%B3%E7%B4%B0-category_no_page)）はリンク先がないため、グリッドに残ります。このとき開発時の警告が出力されます。 - リストが空の場合、セカンダリ行は表示されません。 この設定はホームページにのみ影響します。`` / `` MDX タグはこの設定を無視し、ヘッダーナビ、サイドバー、検索、サイトマップも変わりません。 型: `string[]` · デフォルト: `[]` ## アイデンティティと URL ### siteName ヘッダーとメタデータに表示されるサイト名。ページタイトルは `{page title} | {siteName}` としてレンダリングされます。ほぼ必ず設定する唯一のフィールドです。 デフォルト: `"Docs"` ### siteDescription メタデータ（``、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段](https://zudo-doc.takazudomodular.com/ja/docs/reference/customizing#%E7%AC%AC5%E6%AE%B5-%E2%80%94-%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E3%81%AE%E3%82%A8%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88)を参照してください。 `logo: ""` を指定すると、空パスの CSS マスクを黙って描画する代わりに、設定解決の時点で `TypeError` がスローされます — ロゴを非表示にしたい場合は `false` を、デフォルトのままでよければフィールド自体を省略してください。 デフォルト: `"auto"` ### favicon 各ページの `` に出力される `` のセット。省略すると、`create-zudo-doc` が新規プロジェクトの `public/` に同梱する 4 ファイル構成 — `favicon.svg`、`favicon.ico`（`sizes="any"`）、`favicon-32x32.png`、`favicon-16x16.png` — がこの順で出力されます。 型: `string | FaviconConfig | false` · デフォルト: `undefined`（上記 4 リンクのセット） | 値 | 出力されるもの | |-------|---------------| | 省略 | 上記 4 リンクのデフォルト | | `"auto"` | `siteName` から生成したインライン SVG の `data:` URL アイコンを 1 つ。アセットファイルは不要 | | それ以外の文字列 | そのパスへのリンクを 1 つ。`type` は拡張子から推論 | | `FaviconConfig` オブジェクト | 指定したスロットだけを、常に `svg` → `ico` → `png32` → `png16` の順で出力 | | `false` | favicon のリンクを一切出力しない | | `""` | 設定解決の時点で `TypeError` をスロー — 詳細は下記 | **空文字列は出力されず、拒否されます。** HTML の仕様では空の `href` は「現在のドキュメント自身」に解決されるため、`favicon: ""` を許すと全ページが自分自身の HTML を favicon として黙ってフェッチしてしまいます — 無駄なリクエストであり、タブアイコンとしても壊れています。`zudoDoc({ favicon: "" })` はその代わりにフィールド名を含む `TypeError` をスローします。favicon のリンクを出したくない場合は `false` を、デフォルトの 4 リンクセットでよければフィールドを省略してください。この拒否は `FaviconConfig` の空文字列スロット（例: `favicon: { ico: "" }`）にも同様に適用され、エラーは該当スロット名（`favicon.ico`）を含みます。空の**オブジェクト**（`favicon: {}`、スロットなし）はこの対象外で、これまでどおり何も出力しません。拒否されるのは厳密に空文字列 `""` のみで、`" "` のような空白のみの値はそのまま通過します。 **デフォルトはあくまで規約であり、ファイルの存在チェックではありません。** 実ファイルの有無にかかわらず 4 本のリンクを出力するため、`public/` に `favicon.ico` を置いていないプロジェクトでも全ページに `` が出力され、訪問者のブラウザーコンソールにはもれなく 404 が記録されます。これを避けるには、実際に用意してあるスロットだけをオブジェクト形式で指定します。 ```ts title="zfb.config.ts" 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"` が付きます。 ```ts 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"`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%A2%E3%82%A4%E3%83%87%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%81%A8-url-logo) と同じなので、ヒーローのロゴとブラウザータブのアイコンには同じマークが表示されます。ただし favicon 側は正方形・不透明で、パレットはライト固定です。タブのアイコンは、CSS マスクで描画されるヒーローロゴのようにページのカラーモードへ追従できないためです。 [Dynamic content unavailable in text export] SVG favicon のサポートはブラウザー間でまだムラがあります（特に Safari）。`"auto"` は未対応のブラウザーでも壊れたアイコンにはならず、既定の空アイコンにフォールバックするだけですが、対応範囲を最大化したいプロジェクトは実ファイルの `.ico` / `.png` を用意してオブジェクト形式を使ってください。 `/` で始まる href の値には、設定した [`base`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%A2%E3%82%A4%E3%83%87%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%81%A8-url-base) が前置されます。サブパスにデプロイした場合、`"/favicon.svg"` は `/pj/my-site/favicon.svg` に解決されます。それ以外の値 — `https://…` の絶対 URL や `data:` URL — はそのまま出力されます。 [Dynamic content unavailable in text export] [`head.alternateLinks`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%A2%E3%82%A4%E3%83%87%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%81%A8-url-head) でこのセットを置き換えることはできません。`head` のエントリは favicon ブロックの**後**に出力されるため、そこに `{ rel: "icon" }` を書いてもリンクが 1 本追加されるだけで、ここで出力されるリンクを削除することも上書きすることもできません。セットの内容を変更する手段は `favicon` だけです。 ### siteUrl サイトマップ / canonical / `og:url` のための正規サイトオリジン（例 `"https://example.com"`）。空 = 未設定。 デフォルト: `""` ### base すべての絶対アセット URL の前にマウントされる公開 URL サブパスプレフィックス（例 `"/pj/my-site/"`）。`"/"` = ルートマウント。すべての内部リンク（サイドバー、ナビ、prev/next、検索）は自動的にプレフィックスされます。 デフォルト: `"/"` [Dynamic content unavailable in text export] MDX 内のインラインマークダウンリンク（例 `[text](/docs/some-page)`）は非ルート base 向けに**書き換えられません** — 代わりにコンテンツでは相対リンクを使ってください。 ### trailingSlash 拡張子なしの内部 href に末尾の `/` を付けます。 デフォルト: `false` このルールがビルド時とデプロイホストの間でどう分かれるかは[末尾スラッシュポリシー](https://zudo-doc.takazudomodular.com/ja/docs/develop/trailing-slash-policy)を参照してください。 ### 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` [検索エンジンのインデックス回避](https://zudo-doc.takazudomodular.com/ja/docs/guides/avoid-robots-indexing)を参照してください。 ### head サイト全体のカスタム `` 追加要素（preconnect / preload / stylesheets / meta / alternateLinks）。追加を出力しないなら省略。 型: `SiteHeadConfig` · デフォルト: `undefined` ### metaTags `` / OpenGraph / Twitter カードの出力トグル。 デフォルト: `{ description: true, keywords: false, ogImage: false, ogSiteName: true, twitterCard: false }` | プロパティ | 型 | 説明 | |----------|------|-------------| | `description` | `boolean` | `` を出力 | | `keywords` | `string \| false` | `` の値、または省略 | | `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` **サイトマップが必要なら `sitemap: true` を明示的に設定してください。** デフォルトの `false` では `/sitemap.xml` ルートそのものが出力されず、この URL は 404 になります。`siteUrl` を設定しただけでは有効になりません。canonical や `og:url` のためだけに `siteUrl` を設定するのはごく普通の構成なので、そこから意図を推測することはせず、ビルド時に警告も出しません。この取り決めが明文化されているのは、このリファレンスです。 何も配信しないのは意図的な設計です。よく知られた URL に置かれた空の `` は中立的なプレースホルダーではなく、「このサイトにはインデックス可能な URL が 1 つもない」とクローラーに積極的に宣言するものであり、URL が単に存在しない状態よりも悪い結果になります。生成される `robots.txt` はこの状態ですでに `Sitemap:` 行を省いているため、両者は矛盾することなく一致するようになりました。以前のバージョンは空の `` を出力していましたが、現在は出力しません。 この判定はパッケージのルート注入（`packageOwnedRoutes`、デフォルトで有効）側で行われます。自前で `pages/sitemap.xml.tsx` を用意しているプロジェクトはその外側にあり、そのページが返すものがそのまま使われます。`sitemap` が `false` のままそのページがパッケージのエントリポイントを再エクスポートしている場合は、ビルドが警告を出したうえで空の `` を書き出します。 `metaTags` と `sitemap` を組み合わせたソーシャル共有・検索インデックス設定の全体像は [SEO ガイド](https://zudo-doc.takazudomodular.com/ja/docs/guides/seo) も参照してください。 ### onBrokenMarkdownLinks `.md`/`.mdx` リンクが解決できないときの挙動: `"warn"` はログして続行、`"error"` はビルドを失敗、`"ignore"` は無音。 型: `"warn" | "error" | "ignore"` · デフォルト: `"warn"` この設定は、ビルド後のHTMLにある生の``の存在確認にも適用されます。`"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 }` | プロパティ | 型 | 説明 | |----------|------|-------------| | `defaultMode` | `"light" \| "dark"` | System に従わず、保存済みの選択がない場合に使うライト/ダークのフォールバック | | `lightScheme` | `string` | ライトモードで使うスキーム | | `darkScheme` | `string` | ダークモードで使うスキーム | | `respectPrefersColorScheme` | `boolean` | 保存済み設定がない初回訪問で System を選ぶ | デフォルトの `respectPrefersColorScheme: true` では、保存済みの選択がない初回訪問時に **System** が選ばれ、デバイスのライト/ダーク設定に従います。コンパクトなヘッダーの外観メニューでは **Light**、**Dark**、**System** を選べます。アイコンは次に選ばれる設定ではなく、現在選択されている設定を表します（Light は太陽、Dark は月、System はモニター）。選択は `localStorage` の `zudo-doc-theme` に保存され、再読み込み後も維持されます。 `defaultMode` は引き続きライト/ダークの2値フォールバックです。`respectPrefersColorScheme: false` にすると、保存済みの選択がない初回訪問時は `defaultMode` が使われます。利用者はメニューから System を明示的に選ぶこともでき、その場合は引き続きデバイス設定に従います。`colorMode: false` は単一の固定スキームを保ち、外観メニューは表示しません。 ```ts colorMode: false, // single fixed scheme (colorScheme only) ``` ランプネイティブなモデルとカスタムスキームの追加（下記の `colorSchemes` エスケープハッチ経由）については [Color リファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/color)を参照してください。 ## テーマパック テーマパックは、上記のカラースキームシステムの**上に重なる**インストール可能なデザインバンドルです — すべてのパックがライト/ダーク両方の値を定義するため、外観メニューはどのパックでもそのまま機能します。スイッチャー UI、theme CLI、パックの作り方は[テーマパックリファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/theme-packs)を参照してください。 ### themePack アクティブなテーマパックのスラッグ。`"default"` は zudo-doc 標準の見た目です（パックのスタイルシートは読み込まれません）。解決済みの `themePacks` リストのメンバーである必要があり、未知のスラッグはビルドを大きな声で失敗させます。 デフォルト: `"default"` ### themePackSwitcher 右下のテーマパックスイッチャーフライアウト（と一覧ダイアログ）を全ページにマウントします。 デフォルト: `false` ### themePacks 有効化するパックのスラッグをスイッチャー順で並べたリスト — この並び順がそのままスイッチャーの Prev/Next の巡回順と一覧ダイアログのグリッド順になります。`undefined` は同梱パックすべてを有効化します（`"default"` が先頭、残りはアルファベット順）。明示的なリストが正となります — `"default"` を省いても、自由に並べ替えても構いませんが、重複や未知のスラッグはビルドを大きな声で失敗させます。 デフォルト: `undefined` ```ts themePacks: ["default", "foundry"], ``` ## コンテンツと i18n ### docsDir デフォルトロケールのドキュメントを保持するディレクトリ（プロジェクトルート相対）。 デフォルト: `"src/content/docs"` ### entryDocSlug [バージョン一覧ページ](https://zudo-doc.takazudomodular.com/ja/docs/guides/versioning#%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E4%B8%80%E8%A6%A7%E3%83%9A%E3%83%BC%E3%82%B8)が「最新ドキュメント」へのエントリーポイント（および過去の各バージョンのドキュメントリンク）として使用するドキュメントページのルートスラッグ。先頭・末尾にスラッシュを含まない（例：`"getting-started"`、`"overview/getting-started"`）。実行時のバリデーションは行われず、無効なスラッグは単に404になる。 デフォルト: `"getting-started"` ### dateFormat 日付の表示形式。`"locale"` は組み込みの `Intl` による表示をそのまま使い、それ以外の文字列はトークンパターンとして解釈されます。 型: `DateFormatSetting` · デフォルト: `"locale"` zudo-doc が表示する日付には 5 つの**形**があり、この設定は呼び出し箇所ごとではなく、その形ごと（以下「ロール」）に指定します。ページャーの日付だけを見出しの日付と別の形式にしたいという要望はまずありませんが、カードの短い日付スタンプと本文の完全な日付行は、そもそも別物だからです。 | ロール | デフォルト（`en`） | デフォルト（`ja`） | 表示される場所 | |---|---|---|---| | `full` | `Aug 22, 2026` | `2026年8月22日` | h1 直下の日付行、git メタ情報、ページャー、アセットページ、更新履歴、ノートトレイのリストとタイムライン、グループ化していないサイトツリーの行 | | `monthDay` | `Aug 22` | `8月22日` | ノートトレイのカードグリッド | | `year` | `2026` | `2026年` | ノートトレイのカードグリッド、年グループ見出し | | `yearMonth` | `2026 August` | `2026年8月` | ノートトレイ・サイドバー・サイトツリーの年月グループ見出し | | `numericMonthDay` | `08-22` | `08-22` | サイドバーのトレイ行、サイトツリーのグループ行 | `numericMonthDay` のデフォルトが意図的にロケール非依存になっているのは、これが文章ではなく桁の揃った短いスタンプだからです。どのロケールでも `08-22` になります。パターンを与えれば他のロールと同じように整形されます。 [Dynamic content unavailable in text export] サイドバーとサイトツリーの年グループ見出しは、グループキーをそのまま出力します。どのロケールでも `2026` です。年見出しはもともとフォーマッターを通っておらず、ここでフォーマッターを通すと既存の日本語サイトの表示が黙って `2026年` に変わってしまうためです。一方ノートトレイのカードグリッドは年を整形するので、日本語ページでは `2026年` と表示されます。`year` にパターンを指定すれば両方がそのパターンに従います。見出しはその年の 1 月 1 日に対してパターンを適用するため、`year` のパターンに月や日のトークンを含めるとその境界日が表示されます。 #### 文字列だけを渡すと `full` しか変わらない この設定で唯一つまずきやすいのがここです。文字列単体は `{ full: "…" }` の短縮形なので、h1 直下の日付行やページャーなど `full` を使う場所だけが変わり、カードの日付スタンプ・年月見出し・サイドバーの行はそのまま残ります。 ```ts dateFormat: "YYYY/MM/DD", ``` これらも変えたい場合は、対応するロールを明示してください。 #### ロールとロケール別の上書き オブジェクト形式では 5 つのロールキーに加えて、ロケールコードをキーとする `locales` を指定できます。`locales` の値も同じ 5 つのキーを取ります。 ```ts 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）](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n#%E3%83%AD%E3%82%B1%E3%83%BC%E3%83%AB%E3%81%94%E3%81%A8%E3%81%AE%E6%97%A5%E4%BB%98%E5%BD%A2%E5%BC%8F)も参照してください。 #### サポートするトークン | トークン | 意味 | `2026-08-05`（`en`） | |---|---|---| | `YYYY` | 4 桁の年 | `2026` | | `YY` | 2 桁の年 | `26` | | `MMMM` | 月名（ロケール依存） | `August` | | `MMM` | 月名の短縮形（ロケール依存） | `Aug` | | `MM` | ゼロ埋めした月 | `08` | | `M` | 月 | `8` | | `DD` | ゼロ埋めした日 | `05` | | `D` | 日 | `5` | | `[…]` | リテラルのエスケープ（`[at] YYYY`） | `at 2026` | マッチングの挙動で押さえておきたい点は次のとおりです。 - トークン以外の文字はそのまま出力されるので、`/`、`-`、`.`、空白、`年 月 日` にエスケープは不要です。 - 同じ位置では長いトークンが優先されます。`YYYY` は `YY` に、`MMMM` は `MMM`・`MM`・`M` に勝ちます。 - 置換後の月名は再走査されないため、`March` や `May` の `M` が壊れることはありません。 - 解釈できない並びはビルドを失敗させずにそのまま出力されます。`YYYYY` は年に続けてリテラルの `Y`、`dddd` は `dddd` のままです。 - 角括弧はネストできず、最初の `]` でエスケープが閉じます。閉じない `[` はリテラルとして出力され、後続のトークンは通常どおり解決されます。 - `MMM` と `MMMM` が月名をローカライズできるのは `en`・`ja`・`de` だけで、それ以外のロケールは英語の月名になります。[ロケールごとの日付形式](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n#%E3%83%AD%E3%82%B1%E3%83%BC%E3%83%AB%E3%81%94%E3%81%A8%E3%81%AE%E6%97%A5%E4%BB%98%E5%BD%A2%E5%BC%8F)を参照してください。 [Dynamic content unavailable in text export] トークンの綴りは馴染みがあるという理由で Day.js から借りていますが、これは Day.js 互換ではなく閉じた語彙です。上記の 8 トークンと `[…]` エスケープがすべてで、曜日・時刻・四半期・紀元のトークンもプラグインの仕組みもありません。それ以外はすべてリテラルとして出力されます。 #### 記述例 文字列単体を渡した場合、全ロケールで `full` ロールだけが変わります。h1 直下の日付行とページャーは `2026/08/22` になり、カードの日付スタンプ・年月見出し・サイドバーの行は変わりません。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: "YYYY/MM/DD", }), ); ``` 2 つのロールを全ロケールで指定した場合、`full` は `08/22/2026`、`yearMonth` は `08/2026` になります。`monthDay`・`year`・`numericMonthDay` は `"locale"` のままです。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: { full: "MM/DD/YYYY", yearMonth: "MM/YYYY", }, }), ); ``` ロケール別に指定した場合、英語ページは `Aug 22, 2026`、日本語ページは `2026年8月22日` になります。`yearMonth` は `ja` でのみ上書きしているので、英語はデフォルトの `2026 August`、日本語は `2026年8月` です。 ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ dateFormat: { full: "MMM D, YYYY", locales: { ja: { full: "YYYY年M月D日", yearMonth: "YYYY年M月" }, }, }, }), ); ``` #### オブジェクトを渡すとデフォルトを丸ごと置き換える `zudoDoc()` が指定値をパッケージのデフォルトにマージするのは**トップレベルだけ**です。したがって `dateFormat` にオブジェクトを渡すと、デフォルトの `"locale"` は深くマージされずそのまま置き換わります。ただしこれが問題になることはありません。省略したロールにはリゾルバーが `"locale"` を補うので、結果はデフォルトが意味していたものと同じだからです。 #### 影響しないもの `dateFormat` はあくまで表示の設定です。[フロントマターの記述形式](https://zudo-doc.takazudomodular.com/ja/docs/guides/frontmatter#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E8%A9%B3%E7%B4%B0-date)である `YYYY-MM-DD`、`