Skip to main
Table of Contents

Table of Contents

This page explains and demonstrates how Synticore's HTML compilation pipeline supports table-of-contents style content structure with heading hierarchy, anchor linking, and numbered navigation patterns.

  • Use semantic heading levels (h1-h6) as the source structure.
  • Generate or maintain TOC links that point to compiled heading IDs.
  • Keep section and TOC numbering aligned through shared counter rules.

Pipeline Role

In the HTML compilation workflow, this feature is not just visual styling. It is a content-organization layer that ties together:

  • compiled section anchors,
  • navigable TOC markup,
  • and consistent numbering for headings and links.

That makes long documentation pages easier to scan, navigate, and maintain as content evolves.

Compiler Rules and Requirements

The ToC behavior is driven by the HTML build pipeline (gulp task using @custom/custom-gulp-html-toc) and the project config under option.navigation.toc.

Required for Generation

  • option.navigation.toc.enable must not be false (default: true).
  • Your page must contain the replace marker from option.navigation.toc.replace_text (default: <!-- toc -->).
  • Headings must match option.navigation.toc.selectors (default: h1,h2,h3,h4,h5,h6).

Injection Output Shape

  • The task injects a wrapper section: <section id="section-toc">...</section>.
  • Title node is injected as <span id="toc-title">Table of Contents</span>.
  • If option.navigation.toc.collapsible is true, container is <div id="toc"></div>.
  • If collapsible is false (default), container is <ul id="toc"></ul>.

Depth and Filtering Rules

  • option.navigation.toc.depth controls maximum ToC heading depth (default: 4).
  • option.navigation.toc.ignore_class excludes headings by class (default: toc-ignore).
  • option.navigation.toc.ignore_patterns can exclude files by path/glob; if null, shared navigation ignore patterns are used.
  • option.navigation.toc.wrap_emoji can normalize emoji wrapping in generated labels (optional).

Authoring with toc-ignore

Use toc-ignore on headings that should remain semantic in markup but should not appear in the generated TOC or heading counters.

  • Use it for utility headings that help readers scan a section (such as code labels or callout titles) but are not real sections of the document.
  • Use it when a heading is part of a widget/component interface and should not appear in page-level navigation.
  • Use it to keep knowledge base, docs, and policy page TOCs focused on primary sections rather than every small subheading.
  • Use it when you need semantic heading markup for accessibility/structure but do not want that heading indexed in the compiled TOC.

Heading Prepend and Anchors

  • option.navigation.toc.header_prepend is inserted into heading labels (default: <span class="counter"></span>).
  • option.navigation.toc.header_prepend_selectors controls which heading selectors receive prepend content (default: h2,h3,h4,h5,h6).
  • The task also adds anchor links to headings using the configured anchor template (link icon anchor with ignore--print class).

Reference Structure

Example HTML Pattern 

<section>
  <h1>Documentation Page</h1>

  <span class="toc-title">Table of Contents</span>
  <div id="toc">
    <details class="nav">
      <summary>
        <a class="toc__link" href="#documentation-page-overview">Overview</a>
      </summary>
      <a class="toc__link" href="#documentation-page-overview-scope">Scope</a>
      <a class="toc__link" href="#documentation-page-overview-output">Output</a>
    </details>
  </div>
</section>

<section>
  <h2 id="documentation-page-overview">Overview</h2>
  <h3 id="documentation-page-overview-scope">Scope</h3>
  <h3 id="documentation-page-overview-output">Output</h3>
</section>

<section>
  <h3 class="toc-ignore">CSS</h3>
  <h4 class="toc-ignore">Demo Heading (not indexed)</h4>
</section>

Example Counter Rules 

body { counter-reset: counter_h2; }
h2 { counter-reset: counter_h3; }

h2::before {
  counter-increment: counter_h2;
  content: counter(counter_h2);
}

h3::before {
  counter-increment: counter_h3;
  content: counter(counter_h2) "." counter(counter_h3);
}

Feature Demonstration

Overview

The heading sequence below intentionally repeats levels to show stable hierarchical numbering behavior.

Scope

Input Conventions

Output Conventions

Maintenance

Content Changes

Heading Additions
Heading Removals

Attribution

This page is comprised of my own additions and either partially or heavily modified elements from the following source(s):