Heading-marker TOC

Auto-insert a table of contents after a designated heading.

The headingMarkerToc feature inserts a nested <ul>/<li> table of contents immediately after the first heading whose text matches a configured anchor string (default "TOC").

Enable

// zfb.config.ts
export default defineConfig({
  markdown: {
    features: {
      headingMarkerToc: {
        heading: "TOC",   // default — heading text that triggers insertion
        maxDepth: 2,      // default — 1 = h2 only, 2 = h2+h3, …, max 5
      },
    },
  },
});

Pass true to use all defaults:

headingMarkerToc: true,

Usage

Place a heading with the configured anchor text in your Markdown file:

## TOC

## Introduction

### Background

## Conclusion

The plugin inserts a <ul> list after the ## TOC heading containing links to all subsequent headings within maxDepth levels:

<ul>
  <li><a href="#introduction">Introduction</a>
    <ul>
      <li><a href="#background">Background</a></li>
    </ul>
  </li>
  <li><a href="#conclusion">Conclusion</a></li>
</ul>

Options

Visitor ordering

TocPlugin runs after HeadingLinksPlugin in the hast phase so that id attributes (deduplicated slugs) are already set on each heading when the TOC links are built. Each <a href="#id"> in the TOC mirrors the final, deduplicated slug.

Alternate config key

The same { heading?: string; maxDepth?: number } options object is also reachable through the top-level markdown.toc key:

// zfb.config.ts
export default defineConfig({
  markdown: {
    toc: {
      heading: "TOC",
      maxDepth: 2,
    },
  },
});

Unlike markdown.features.headingMarkerToc, markdown.toc does not accept the true boolean shorthand — only the options object. markdown.features.headingMarkerToc (documented above) is the canonical key — prefer it, since every other opt-in Markdown feature lives under markdown.features.*. markdown.toc wires the same TocPlugin and is kept for backward compatibility.