markdown-toc

A Python CLI tool to generate a table of contents for Markdown files. Zero dependencies.

Features

• Parse headings from # to ######
• Generate linked TOC with proper indentation
• Update existing TOC in-place between <!-- TOC --> markers
• Configurable maximum heading depth
• Process multiple files at once
• Skip headings matching a regex pattern
• Ordered (numbered) or unordered list output
• Output to stdout or edit files in-place
• Skips headings inside code blocks
• GitHub-compatible anchor links

Installation

git clone https://github.com/Anuar-boop/markdown-toc.git
cd markdown-toc
chmod +x markdown_toc.py

# Optional: add to PATH
sudo ln -s "$(pwd)/markdown_toc.py" /usr/local/bin/markdown-toc

Usage

# Generate TOC and print to stdout
python3 markdown_toc.py README.md

# Limit to h1-h3 headings
python3 markdown_toc.py -d 3 README.md

# Use numbered list
python3 markdown_toc.py --ordered README.md

# Update TOC in-place (inserts between <!-- TOC --> markers)
python3 markdown_toc.py -i README.md

# Skip headings matching a pattern
python3 markdown_toc.py --skip "Table of Contents|TOC" README.md

# Process multiple files
python3 markdown_toc.py docs/*.md

In-place Mode

Add TOC markers to your Markdown file:

# My Document

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

## First Section
...

Then run:

python3 markdown_toc.py -i README.md

The TOC will be generated between the markers. Run again to update.

Options

Option	Description
-d, --max-depth N	Maximum heading depth, 1-6 (default: 6)
-o, --ordered	Use numbered list instead of bullets
-i, --inplace	Update file in-place between TOC markers
-s, --skip PATTERN	Skip headings matching regex pattern
--version	Show version

Example Output

Given a file with these headings:

# Project
## Installation
## Usage
### CLI
### API
## License

The generated TOC:

- [Project](#project)
  - [Installation](#installation)
  - [Usage](#usage)
    - [CLI](#cli)
    - [API](#api)
  - [License](#license)

Requirements

• Python 3.6+
• No external dependencies

License

MIT