**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.

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

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

```md
## 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](https://zudo-doc.takazudomodular.com/docs/markdown-features/heading-marker-toc), and the [TOC export](https://zudo-doc.takazudomodular.com/docs/markdown-features/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:

```md
[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 `id`s.
- 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.