mdbook-toc Jan-Erik Rediger

Use this command to install mdbook-toc:

winget install --id=badboy.mdbook-toc -e

A preprocessor for mdbook to add inline Table of Contents support.

mdbook-toc is a preprocessor for mdbook designed to add inline Table of Contents (TOC) support. It automatically generates a TOC based on headings in your document, enhancing navigation and readability.

Key Features:

Automatic TOC Generation: Converts a specified marker (e.g., ) into a structured TOC.
Customizable Marker: Supports different markers for various platforms, such as GitLab or GitHub.
Configurable Depth: Allows users to define the maximum header level included in the TOC.
Seamless Integration: Easily configured through book.toml with minimal setup.
Cross-Platform Support: Works across multiple environments and can be installed via winget.

Audience & Benefit: Ideal for technical writers, documentation teams, and content creators using mdbook to author books or documentation. It simplifies the process of adding TOCs, improving document structure and user experience.

mdbook-toc

A preprocessor for mdbook to add inline Table of Contents support.

It turns this marker:

into a Table of Contents based on headings of the chapter following the marker.

Installation

If you want to use only this preprocessor, install the tool:

cargo install mdbook-toc

Add it as a preprocessor to your book.toml:

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

Finally, build your book as normal:

mdbook path/to/book

Configuration

Custom TOC marker

The default marker is:

If you wish to use a different marker, such as the GitLab marker [[_TOC_]], you must add the following settings to your book.toml.

[preprocessor.toc]
marker = "[[_TOC_]]"

You can also use multi-line markers such as the GitHub marker, which is:

* auto-gen TOC;
{:toc}

Configure the string with a newline:

[preprocessor.toc]
marker = "* auto-gen TOC;\n{:toc}"

or with multi-line strings:

[preprocessor.toc]
marker = """* auto-gen TOC;
{:toc}"""

Maximum header level

By default the ToC will include headings up to level 4 (####). This can be configured in your book.toml as follows:

[preprocessor.toc]
max-level = 4