タグ

ドキュメントページ横断ナビゲーション。

概要

タグは、サイドバーのカテゴリが異なっていても同じトピックを扱うドキュメントページをまとめるための、カテゴリ横断的な仕組みです。たとえば Guides の下にあるデプロイ関連のページと、Reference にあるトラブルシューティングページの両方に deployment タグを付けておけば、そのトピックを探している読者は両方のページにたどり着けます。

次のような場面で使います。

• 複数のカテゴリにまたがるトピック（例: deployment、i18n、accessibility）。
• サイドバー上では隣り合わないが、関連性の高いページを読者に発見してもらいたいとき。
• ディレクトリ構成を変えずに補助的なナビゲーションを追加したいとき。

タグはサイドバーを補完するものであり、置き換えるものではありません。サイドバーは構造を反映し、タグはトピックを反映します。

タグを追加する

タグはページの frontmatter に文字列の配列として指定します。

---
title: Deploying to Cloudflare Pages
sidebar_position: 3
tags: [deployment, hosting]
---

1 ページに付けられるタグの数に制限はありません。タグは大文字・小文字を区別する文字列なので、表記を統一しておきます（下記の「命名規則」を参照）。

タグが表示される場所

ビルド後のサイトでは、タグは次の 3 か所に現れます。

ページのバッジ列

タグが 1 つ以上付いたページでは、タグバッジの列が表示され、各バッジはそのタグのインデックスページへリンクします。これは DocTags コンポーネント（TagNav に variant="page" を指定したもの）によって描画されます。

バッジ列の表示位置は <code>tagPlacement</code> 設定で次の 2 つから選べます。

• "after-title"（デフォルト） — ページタイトルの直下、本文の上にバッジ列を表示します。タグがページの概要を一目で示すラベルであり、スクロールせずに見せたいときに向いています。
• "before-pager" — コンテンツの末尾、前後ページャーのすぐ上にバッジ列を表示します。タグがページを読み終えたあとに参照するメタデータ的な位置づけのときに向いています。

どちらか一方だけが有効で、設定はサイト全体に適用されます。

ホームページの「All Tags」セクション

settings.docTags が true で、かつ現在のロケールにタグ付きページが 1 つ以上存在する場合、ホームページに「All Tags」セクションが表示され、利用中のすべてのタグとそのインデックスページへのリンクが並びます。タグ付きページが 1 つもないときは、このセクションは自動的に非表示になります。

タグインデックスとタグごとのページ

• /ja/docs/tags/ — 利用中のタグとページ数を一覧表示するグローバルなタグインデックス。
• /ja/docs/tags/[tag] — タグごとに 1 ページ。そのタグが付いたすべてのページを一覧表示します。

これらのルートは frontmatter から自動生成されるため、手動で作る必要はありません。

命名規則

タグ名を統一しておくと、タグインデックスがすっきりし、deployment と Deployment のような重複表記を避けられます。

• 小文字 — タグは表示用のテキストではなくスラッグとして扱います。
• 複数単語は kebab-case にする — color-scheme を使い、colorScheme や color_scheme は避けます。
• 短く、具体的に — internationalization-and-localization より i18n が望ましい。
• ロケールをまたいで一貫 — EN と JA の frontmatter で同じタグスラッグを使います（下記参照）。

i18n の挙動

タグはロケールをまたいだ共通の識別子であり、翻訳するラベルではありません。

• 同じタグスラッグを EN と JA の frontmatter で使います（例: 両方のファイルで tags: [deployment]）。
• タグインデックスはロケールごとに別々です。EN の /docs/tags/deployment は EN ページを一覧します。JA の /ja/docs/tags/deployment はまず JA に翻訳されたページを表示し、翻訳がまだ存在しないスラッグについては EN ページにフォールバックします — 未翻訳の EN ドキュメントもそのまま JA のタグページに表示されるため、「翻訳が無いから消える」ということは起きません。
• タグスラッグは翻訳しません。 JA ファイルで deployment を デプロイ に置き換えると、タグが無関係な 2 つのグループに分かれ、ロケール横断のモデルが壊れます。

ロケール別の表示ラベルが欲しくなった場合は将来的な拡張課題です。現時点ではスラッグが識別子と表示ラベルを兼ねています。

設定

タグの表示は src/config/settings.ts の docTags 設定で制御します。有効（デフォルト）のときは、ページ下部のタグバッジ列とホームページの「All Tags」セクションが描画されます。false にするとこれらの表示は非表示になりますが、/ja/docs/tags/ のインデックスや /ja/docs/tags/[tag] のページはビルドされ、URL から直接アクセスすればそのまま到達できます。

詳細はConfigurationを参照してください。

チームプロジェクトへのスケール

著者が片手で数えきれなくなると、自由記述のタグはドリフトし始めます。zudo-doc はドキュメントベースが大きくなってもタグインデックスを整えておくためのボキャブラリ対応ガバナンスワークフローを備えています。

• タグガバナンス — 正規ボキャブラリを整備し、tagGovernance: "warn" | "strict"で強制する。
• タグ監査 — pnpm tags:auditが unknown、deprecation、エイリアス、ニアデュプリケート、オーファンを報告する。エイリアスはバイト安定な--fixで書き換えられ、--ciでpnpm b4pushと連携できる。
• タグサジェスト — 新しいページに正規タグを提案するオプション機能(pnpm tags:suggest)。
• フッタータグリスト — ボキャブラリを読者向けに公開するオプトインのフッターカラム。

関連する frontmatter フィールド

タグナビゲーションと相互作用する frontmatter フィールドがいくつかあります。

• unlisted: true — unlisted のページは、サイドバーから除外されるのと同様に、タグインデックス（/ja/docs/tags/[tag] の一覧）やホームページの「All Tags」セクションから除外されます。ただし、ページ自体を URL から直接開いた場合、そのページ下部のタグバッジ列は引き続き表示されます。
• draft: true — draft のページは本番ビルドから完全に除外されるため、本番環境ではいずれのタグページにも表示されません。

フィールド全体の一覧は Frontmatter を参照してください。