Markdown Table of Contents Generator

Generates a table of contents (TOC) for Markdown files. Detects headers and creates a linked TOC. Updates existing TOCs in-place when markers are present; otherwise prints to stdout.

Table of Contents

1. Quick Start
2. Features
3. Installation
4. Usage
5. Configuration
6. Integration with Vim

Quick Start

Add TOC markers to your Markdown file:

<!-- TOC -->
<!-- /TOC -->

Run:

toc-markdown README.md

The TOC appears between the markers. Run again to update.

Without markers, the TOC prints to stdout for manual insertion.

Features

• Generates a table of contents from Markdown headers.
• Updates existing TOCs between markers or prints to stdout.
• Supports headings from levels 2 to 3 by default (configurable).
• Provides clickable links to sections.
• Preserves file structure and formatting.

Installation

Requirements: Python 3.11+

Using uv (recommended):

uv tool install toc-markdown

Using pip:

pip install toc-markdown

Usage

Run toc-markdown on a .md or .markdown file:

# Update file in-place (requires TOC markers)
toc-markdown path/to/file.md

# Print TOC to stdout (no markers in file)
toc-markdown path/to/file.md

# Customize header levels
toc-markdown README.md --min-level 1 --max-level 4

# Change list style
toc-markdown README.md --list-style "*"
toc-markdown README.md --list-style "-"

# Custom header text
toc-markdown README.md --header-text "## Contents"

# Preserve Unicode in slugs
toc-markdown README.md --preserve-unicode

# Custom indentation
toc-markdown README.md --indent-chars "  "

# Custom markers
toc-markdown README.md --start-marker "<!-- BEGIN TOC -->" --end-marker "<!-- END TOC -->"

Safety Limits

• Only regular Markdown files (.md, .markdown) are accepted.
• Files larger than 10 MiB are rejected. Increase via max_file_size in config or TOC_MARKDOWN_MAX_FILE_SIZE environment variable (up to 100 MiB).
• Lines longer than 10,000 characters are rejected. Increase via max_line_length in config or TOC_MARKDOWN_MAX_LINE_LENGTH environment variable.
• Files with more than 10,000 headers are rejected. Increase via max_headers in config.
• Files must be valid UTF-8.
• Updates use atomic writes via temporary files.

Run toc-markdown --help for all options.

Configuration

Create .toc-markdown.toml in your project root:

[toc-markdown]
min_level = 2
max_level = 3
list_style = "1."

Options

CLI flags override config file values.

Integration with Vim

Example mapping (for files with TOC markers):

autocmd FileType markdown nnoremap <buffer> <leader>t :w<cr>:silent !toc-markdown %:p<cr>:e<cr>

Press <leader>t in normal mode to save, update the TOC, and reload the buffer.

For files without markers (insert TOC at cursor):

autocmd FileType markdown nnoremap <buffer> <leader>T :r !toc-markdown %:p<cr>