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.

README

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