Heading Links

作成 2026年5月28日更新 2026年7月24日Takeshi Takatsudo

h2 以上の見出しにスラグベースの id 属性と自己参照アンカーリンクを追加します。

Core 機能 — 常に有効です。見出し ID は階層形式です。

概要

h2 以上のすべての見出しに以下が自動的に付与されます。

zfb 独自の slugify で見出しテキストから生成されたスラグベースの id 属性（github-slugger に近い挙動ですが、. や / などの記号を除去せず - にまとめます）。
見出しテキストの後に追加される、空の自己参照アンカー要素。読者がページ内の直接リンクをコピーできます。
重複解消: 同じスラグが複数生成される場合、カウンターサフィックスが付与されます（overview、overview-1、overview-2 など）。

h1 には id が付与されません。ドキュメント唯一の h1 はフロントマターのページタイトルです。

zudo-doc は常に zfb の階層見出し ID を有効にします。パッケージプリセットと右側 TOC の抽出処理は同じ割り当て規約を使うため、ユーザー向けの方式設定なしでレンダリング ID と TOC アンカーが同期します。

// zudoDoc() が内部的に配線する内容
markdown: {
  features: {
    headingIds: { strategy: "hierarchical" },
  },
}

各見出しの id は、祖先の連なりを - で結合したプレフィックスを持ちます。

## Foo

### Moo

#### Mew

は id="foo"、id="foo-moo"、id="foo-moo-mew" としてレンダリングされます。見出し内アンカーの href、右側 TOC、Heading Marker TOC、TOC export はすべて同じ ID に従います。

詳細:

完全パスが重複した場合は重複カウンターが付与されます（a-b、a-b-1）。
重複解消された親はその最終 ID を子に与えます。2 つ目の ## Foo は foo-1 となり、その配下の ### Bar は foo-1-bar になります。
階層アンカーは見出しのアウトラインから再構築でき、衝突を減らせます（URL が長くなる代わりに）。

各見出しに安定した id が付与されるため、別のページの特定セクションにリンクできます。ネストした見出しには祖先プレフィックス付きの形式を使います。

[Moo セクションを参照](./other-page.mdx#foo-moo)

zudo-doc の右側 TOC ビルダー（pages/lib/_extract-headings.ts）も同じ割り当て処理をミラーしているため、TOC の href="#…" 値は常にレンダリングされた見出し id と一致します。
オプトインの Heading Marker TOC 機能は、このプラグインが生成した安定した見出し識別子に依存します。headingMarkerToc が有効な場合、Heading Links の後で実行されます。