Table of Contents generated with DocToc

• DocToc
  • Prerequisites
  • Installation
  • Usage
  • Options
  • Examples
  • Features
  • GitHub
  • License
  • Contribution

DocToc

DocToc is a command-line tool that automatically generates and updates a table of contents (TOC) for Markdown files. It scans your Markdown, identifies headers, and inserts a TOC with clickable links — skipping headers inside fenced code blocks.

Prerequisites

• Python 3.8+
• pip

Installation

pip install doctoc

Or from source:

git clone https://github.com/ktechhub/doctoc.git
cd doctoc
pip install .

Usage

doctoc [OPTIONS] MARKDOWN_FILES...

MARKDOWN_FILES accepts one or more file paths or glob patterns:

doctoc README.md
doctoc docs/README.md CHANGELOG.md
doctoc '**/*.md'

On the first run, DocToc inserts the TOC at the top of the file. On subsequent runs it updates the existing TOC in place.

Options

Examples

Basic — generate or update TOC:

doctoc README.md
# Success: wrote TOC to README.md

Custom output file:

doctoc README.md -o README_with_toc.md
# Success: wrote TOC to README_with_toc.md

Limit TOC depth to H1 and H2 only:

doctoc README.md --max-depth 2

Custom TOC title:

doctoc README.md --title "## Contents"

Check hyperlinks after generating TOC:

doctoc README.md --check-links
# Success: wrote TOC to README.md
# Checking hyperlinks in README.md...
# VALID: [DocToc](#doctoc)
# VALID: [Installation](#installation)
# VALID: [GitHub repository](https://github.com/ktechhub/doctoc)
# INVALID: [Broken](#missing-section)

Exclude specific headers from the TOC:

doctoc README.md --exclude "Appendix"

Process all Markdown files recursively:

doctoc '**/*.md'

CI check — fail if a TOC is stale, without writing:

doctoc --check '**/*.md'
# OK: README.md is up to date
# STALE: docs/CONTRIBUTING.md is out of date

Features

• Generates and updates a TOC based on Markdown headers.
• Skips headers inside fenced code blocks (``` and ~~~).
• Supports multiple files and glob patterns in a single invocation.
• --max-depth to limit which heading levels appear in the TOC.
• --exclude to omit specific headers from the TOC by matching text (repeatable).
• --title to customise the TOC heading line.
• Link checker validates both internal anchor links and external HTTP(S) URLs, with a timeout and clear error output.
• Writes to an optional output file instead of overwriting the source.
• --check for CI: reports stale TOCs with a non-zero exit code, without modifying any file.

GitHub

For more details, visit the GitHub repository.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Contribution

If you want to contribute, kindly see contribution.