Table of contents

Usage

Register toc() with the parser and each renderer. Heading IDs are supplied by default; combine it with heading anchors to customize them.

import io.heapy.kotmark.ext.heading.anchor.headingAnchor
import io.heapy.kotmark.ext.toc.toc
import io.heapy.kotmark.extensions
import io.heapy.kotmark.parser.parser
import io.heapy.kotmark.renderer.html.htmlRenderer

fun renderWithToc(markdown: String): String {
    val extensions = extensions {
        toc { headingLevels = 2..6 }
        headingAnchor { idPrefix = "section-" }
    }
    val document = parser { extensions(extensions) }.parse(markdown)
    return htmlRenderer { extensions(extensions) }.render(document)
}

Example

[TOC]

## Getting started
### Install
## Usage

<ul>
<li><a href="#section-getting-started">Getting started</a>
<ul>
<li><a href="#section-install">Install</a></li>
</ul>
</li>
<li><a href="#section-usage">Usage</a></li>
</ul>
<h2 id="section-getting-started">Getting started</h2>
<h3 id="section-install">Install</h3>
<h2 id="section-usage">Usage</h2>

Configuration and behavior

Both [TOC] and [[_TOC_]] match case-sensitive standalone lines. Code blocks, inline occurrences and escaped markers keep their ordinary meaning. Use markers = listOf("{{contents}}") to replace the defaults. headingLevels = 2..4 selects an inclusive level range; the default is 1..6.

The default TocPlacement.MARKERS requires an explicit marker. Choose PREPEND_IF_MISSING or APPEND_IF_MISSING to insert one automatically. Multiple markers each show the same outline. No matching headings means no HTML or text outline. Skipped heading levels nest under the nearest preceding lower-level entry, without empty list items.

HTML produces a nested unordered list with plain text labels and matching heading IDs, including duplicates and Unicode. Markdown preserves the markers for later regeneration. Plain text produces a bullet outline without links. Text, code, link labels and image alt text contribute to labels; raw HTML tags and opaque custom inline literals do not.

Headings in standard block quotes and lists are included. Custom block contents, including footnote definitions and alerts, are excluded because their renderers may hide or defer them. The extension owns HTML heading rendering; register custom node renderers first and keep their IDs consistent with the TOC. Custom heading attribute providers run once per heading before output and must provide unique, nonempty IDs. Generated links use the normal URL resolution and escaping pipeline.