Heading Links

Adds slug-based id attributes and self-referencing anchor links to every heading.

Core feature — always active. Heading IDs are hierarchical.

What it does

Every heading at h2 and below automatically receives:

1. A slug-based id attribute derived from the heading text using zfb's own slugify (github-slugger-like, but it collapses punctuation such as . and / to - rather than stripping it).

2. An empty self-referencing anchor element appended after the heading text, so readers can copy a direct deep-link.

3. Deduplication: when the same slug would appear more than once in a document, a counter suffix is appended (overview, overview-1, overview-2, …).

h1 is never assigned an id — the page title (from frontmatter) is the document's only h1.

Hierarchical IDs

zudo-doc always enables zfb's hierarchical heading IDs. The package preset and the right-hand TOC extractor use the same allocation contract, so rendered IDs and TOC anchors stay in sync without a user-facing strategy setting.

// what zudoDoc() wires internally
markdown: {
  features: {
    headingIds: { strategy: "hierarchical" },
  },
}

Each heading's id is prefixed with its ancestor chain, joined by -:

## Foo

### Moo

#### Mew

renders as id="foo", id="foo-moo", id="foo-moo-mew". The in-heading anchor href, the right-hand TOC, the Heading Marker TOC, and the TOC export all follow the same IDs.

Details:

• A duplicated full path still gets the dedup counter (a-b, a-b-1).

• A deduplicated parent contributes its final ID to children: a second ## Foo becomes foo-1, so its ### Bar becomes foo-1-bar.

• Hierarchical anchors are reconstructible from the heading outline and reduce collisions, at the cost of longer URLs.

Deep-linking

Because each heading carries a stable id, you can link to any section of a page from another page. Use the ancestor-prefixed form for nested headings:

[See the Moo section](./other-page.mdx#foo-moo)

Notes

• zudo-doc's right-hand TOC builder (pages/lib/_extract-headings.ts) mirrors the same allocator, so the TOC href="#…" values always match the rendered heading ids.

• The Heading Marker TOC opt-in feature depends on the stable heading identifiers produced by this plugin. When headingMarkerToc is enabled, it runs after heading links have been applied.