フッタータグリスト

サイトフッターのカラムブロックとしてタグボキャブラリを読者に公開するオプトイン機能。

概要

フッタータグリストは、既存のフッターグリッドの中にレンダリングされるタグの索引です。読者は今開いているドキュメントから離れずに、常にすべてのタグページへアクセスできるようになります。

この機能はデフォルトでオフです。zfb.config.tsでfooter.taglist.enabledをtrueにするまで、フッターの見た目は従来と変わりません。新しいscaffoldでは、この設定だけでは空のタグリストになります。chrome にタグローダーとボキャブラリの binding がないためです。ページごとのタグバッジ行やトップページの"All Tags"セクションも影響を受けません。

有効化

既存のfooter設定にtaglistブロックを追加します。

footer: {
  links: [
    // ...existing footer link columns
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Your Project.`,
  taglist: {
    enabled: true,
    title: "Tags",
    groupBy: "group",
    groupTitles: {
      topic: "By topic",
      type: "By type",
      level: "By level",
    },
    locales: {
      ja: {
        title: "タグ",
        groupTitles: {
          topic: "トピック別",
          type: "種類別",
          level: "レベル別",
        },
      },
    },
  },
},

enabled以外のフィールドはすべて任意です。省略した項目には妥当なデフォルトが適用されます。

ボキャブラリとロケール対応の件数ローダーを提供するbindingsモジュールを追加します。ローダーの 契約は正確に(lang: string) => readonly { tag: string; count: number }[]です。静的なリストを 返すのではなく、コンテンツコレクションからエントリーを導出してください。

import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
import { tagVocabulary } from "./tag-vocabulary";
import { collectTagsForLocale } from "./tag-data";

function loadTagsForLocale(
  lang: string,
): readonly { tag: string; count: number }[] {
  return collectTagsForLocale(lang).map(({ tag, count }) => ({ tag, count }));
}

export const chromeBindings = defineChromeBindings({
  loadTagsForLocale,
  tagVocabulary,
});

zudoDoc()からそのモジュールを指定し、同じボキャブラリをビルド時のタグ設定に渡します。

import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";
import { tagVocabulary } from "./src/tag-vocabulary";

export default defineConfig(
  zudoDoc({
    // ...your settings, including footer.taglist.enabled: true
    tagVocabulary: true,
    tagVocabularyEntries: tagVocabulary,
    chromeBindingsModule: "./src/chrome-bindings.ts",
  }),
);

groupBy: "group"と"flat"

タグリストは2つのモードでレンダリングできます。

• groupBy: "group" — バインドしたボキャブラリのgroupごとに1カラム。順序はその group が最初に登場する順です。ボキャブラリが有効なとき(tagVocabulary: trueかつtagGovernance !== "off")のデフォルトです。各カラムのタイトルはgroupTitles[<group>]から取られ、未指定なら group 名を先頭大文字にしたもの(topic → Topic)にフォールバックします。

• groupBy: "flat" — titleを見出しにした単一のアルファベット順カラム。ボキャブラリが無効のときは強制的にこれになります。タグがほんの少ししかなくグループ表示ではスカスカになる場合にも便利です。

タグが増えてグループ表示で topic と type が実際に分離されるようになったら"group"へ切り替えます。それまでは"flat"で十分です。

このリポジトリのsrc/config/tag-vocabulary.tsはショーケース専用の実装例です。新しいscaffoldにはsrc/config/ディレクトリがありません。プロジェクトに合う場所にボキャブラリを作成し、上記のようにtagVocabularyEntriesとchromeBindingsを通して配線してください。

ロケールオーバーライド

タグリストが表示する文字列はカラムタイトルだけなので、ロケールオーバーライドは小さく保てます。localesマップは設定のlocalesと同じロケールコードをキーにします。

taglist: {
  enabled: true,
  title: "Tags",
  groupTitles: { topic: "By topic", type: "By type", level: "By level" },
  locales: {
    ja: {
      title: "タグ",
      groupTitles: { topic: "トピック別", type: "種類別", level: "レベル別" },
    },
  },
},

ロケールオブジェクトに存在するキーだけがデフォルトロケールの文字列を上書きし、無いキーはフォールバックします。タグ id そのものは翻訳されません——理由はtags ガイドの i18n セクションを参照してください。

読者に見える内容

少なくとも1つのドラフトでも unlisted でもないページから参照されているボキャブラリタグは、そのタグのインデックスページ(/docs/tags/<id>/または/{locale}/docs/tags/<id>/)へのリンクとして表示されます。空のグループは折りたたまれ、埋めたカラムぶんだけ場所を取ります。

関連

• タグガバナンス — タグリストを形作るボキャブラリと group 宣言。

• タグ — ページごとのタグバッジ行とトップページのタグインデックス。

• フッター — フッター設定の残りの部分。