## 概要 タグは、サイドバーのカテゴリが異なっていても同じトピックを扱うドキュメントページをまとめるための、**カテゴリ横断的な**仕組みです。たとえば Guides の下にあるデプロイ関連のページと、Reference にあるトラブルシューティングページの両方に `deployment` タグを付けておけば、そのトピックを探している読者は両方のページにたどり着けます。 次のような場面で使います。 - 複数のカテゴリにまたがるトピック（例: `deployment`、`i18n`、`accessibility`）。 - サイドバー上では隣り合わないが、関連性の高いページを読者に発見してもらいたいとき。 - ディレクトリ構成を変えずに補助的なナビゲーションを追加したいとき。 タグはサイドバーを**補完するもの**であり、置き換えるものではありません。サイドバーは構造を反映し、タグはトピックを反映します。 ## タグを追加する タグはページの frontmatter に文字列の配列として指定します。 ```mdx --- title: Deploying to Cloudflare Pages sidebar_position: 3 tags: [deployment, hosting] --- ``` 1 ページに付けられるタグの数に制限はありません。タグは大文字・小文字を区別する文字列なので、表記を統一しておきます（下記の「命名規則」を参照）。 ## タグが表示される場所 ビルド後のサイトでは、タグは次の 3 か所に現れます。 ### ページのバッジ列 タグが 1 つ以上付いたページでは、タグバッジの列が表示され、各バッジはそのタグのインデックスページへリンクします。これは `DocTags` コンポーネント（`TagNav` に `variant="page"` を指定したもの）によって描画されます。 [`tagPlacement`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%BF%E3%82%B0-tagplacement) 設定は 2 つの値を受け付けますが、実際に配線されているのは 1 つだけです。 - `"after-title"`（デフォルト） — ページタイトルの直下、本文の上にバッジ列を表示します。現状、レンダラーが実装しているのはこの配置のみです。 - `"before-pager"` — **まだ配線されていません**（[#2140](https://github.com/zudolab/zudo-doc/issues/2140)）。この値を設定しても効果はなく、バッジ列は常に `after-title` の位置に表示されます。 ### ホームページの「All Tags」セクション `settings.docTags` が `true` で、かつ現在のロケールにタグ付きページが 1 つ以上存在する場合、ホームページに「All Tags」セクションが表示され、利用中のすべてのタグとそのインデックスページへのリンクが並びます。タグ付きページが 1 つもないときは、このセクションは自動的に非表示になります。 ### タグインデックスとタグごとのページ - [/ja/docs/tags/](/ja/docs/tags/) — 利用中のタグとページ数を一覧表示するグローバルなタグインデックス。 - `/ja/docs/tags/[tag]` — タグごとに 1 ページ。そのタグが付いたすべてのページを一覧表示します。 これらのルートは frontmatter から自動生成されるため、手動で作る必要はありません。 ## 命名規則 タグ名を統一しておくと、タグインデックスがすっきりし、`deployment` と `Deployment` のような重複表記を避けられます。 - **小文字** — タグは表示用のテキストではなくスラッグとして扱います。 - 複数単語は **kebab-case** にする — `color-scheme` を使い、`colorScheme` や `color_scheme` は避けます。 - **短く、具体的に** — `internationalization-and-localization` より `i18n` が望ましい。 - **ロケールをまたいで一貫** — プライマリと設定した各ロケールの frontmatter で同じタグスラッグを使います（下記参照）。 [Dynamic content unavailable in text export] 新しいタグを導入する前に、[/ja/docs/tags/](/ja/docs/tags/) のインデックスを眺めて、近い意味のタグがすでに存在しないか確認します。 ## i18n の挙動 タグはロケールをまたいだ**共通の識別子**であり、翻訳するラベルではありません。 - プライマリと設定した各ロケールの frontmatter で同じタグスラッグを使います（例: ミラーした各ファイルで `tags: [deployment]`）。 - タグインデックスはロケールごとに別々です。プライマリの `/docs/tags/deployment` はプライマリページを一覧します。`/ja/docs/tags/deployment` のような追加ロケールでは、まず翻訳済みページを表示し、翻訳がまだ存在しないスラッグについては **プライマリページにフォールバックします** — 未翻訳のプライマリドキュメントもそのロケールのタグページに表示されるため、「翻訳が無いから消える」ということは起きません。 - **タグスラッグは翻訳しません。** JA ファイルで `deployment` を `デプロイ` に置き換えると、タグが無関係な 2 つのグループに分かれ、ロケール横断のモデルが壊れます。 ロケール別の表示ラベルが欲しくなった場合は将来的な拡張課題です。現時点ではスラッグが識別子と表示ラベルを兼ねています。 ## 設定 タグの表示は `zfb.config.ts` の `docTags` フィールドで制御します。有効（デフォルト）のときは、ページ下部のタグバッジ列とホームページの「All Tags」セクションが描画されます。`false` にするとこれらの表示は非表示になりますが、`/ja/docs/tags/` のインデックスや `/ja/docs/tags/[tag]` のページはビルドされ、URL から直接アクセスすればそのまま到達できます。 詳細は[Configuration](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration)を参照してください。 ## チームプロジェクトへのスケール 著者が片手で数えきれなくなると、自由記述のタグはドリフトし始めます。zudo-doc はドキュメントベースが大きくなってもタグインデックスを整えておくためのボキャブラリ対応ガバナンスワークフローを備えています。 - [タグガバナンス](https://zudo-doc.takazudomodular.com/ja/docs/guides/tag-governance) — 正規ボキャブラリを整備し、`tagGovernance: "warn" | "strict"`で強制する。 - [タグ監査](https://zudo-doc.takazudomodular.com/ja/docs/guides/tags-audit) — `pnpm tags:audit`が unknown、ニアデュプリケート、オーファンを報告し、`--ci`で`pnpm b4push`と連携できる。 - [タグサジェスト](https://zudo-doc.takazudomodular.com/ja/docs/guides/tags-suggest) — 新しいページに正規タグを提案するオプション機能(`pnpm tags:suggest`)。 - [フッタータグリスト](https://zudo-doc.takazudomodular.com/ja/docs/guides/footer-taglist) — ボキャブラリを読者向けに公開するオプトインのフッターカラム。 ## 関連する frontmatter フィールド タグナビゲーションと相互作用する frontmatter フィールドがいくつかあります。 - **`unlisted: true`** — unlisted のページは、サイドバーから除外されるのと同様に、タグインデックス（`/ja/docs/tags/[tag]` の一覧）やホームページの「All Tags」セクションから除外されます。ただし、ページ自体を URL から直接開いた場合、そのページ下部のタグバッジ列は引き続き表示されます。 - **`draft: true`** — draft のページは本番ビルドから完全に除外されるため、本番環境ではいずれのタグページにも表示されません。 フィールド全体の一覧は [Frontmatter](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-tags) を参照してください。