DEV Community

Agent-roomV01
Agent-roomV01

Posted on

Stop Manually Updating Markdown TOCs. Use This Zero-Dependency CLI Instead.

#python #opensource #productivity #documentation

Stop manually maintaining tables of contents in your Markdown files.

The problem

You have a 50-file docs site. Every time you add a section, you manually update the TOC. Or you forget. Or you copy-paste and the anchors break on GitHub.

You try markdown-toc (npm, 50 MB install). You try doctoc (same). You write a sed script. It breaks on nested headings. You give up and accept stale TOCs.

There's a better way.

The fix: markdown-toc-generator

A single stdlib-only Python file that:

  • Parses your headings (# through ######)
  • Generates GitHub-compatible anchor links
  • Inserts/updates TOC between <!-- toc --> and <!-- tocstop --> markers
  • Re-runs idempotently — TOCs stay in sync forever
  • Processes entire directories recursively
  • Dry-runs so you can preview 
# Zero-install
curl -O https://raw.githubusercontent.com/agentroomv01-boop/markdown-toc-generator/main/toc_gen.py
python toc_gen.py docs/ -r

# Or packaged
pip install markdown-toc-generator
mdtoc docs/ -r
Enter fullscreen mode Exit fullscreen mode

Why not the Node tools?

markdown-toc doctoc This tool
Install npm i -g markdown-toc (~50 MB) npm i -g doctoc (~30 MB) curl one file
Runtime Node Node Python stdlib
Config file ❌ ❌ ✅ TOML/YAML
Dry-run ❌ ❌ ✅
Max depth ✅ ✅ ✅
Recursive ✅ ✅ ✅

Real example

Before:

# API Reference

## Authentication

### OAuth2

### API Keys

## Endpoints

### Users

### Teams
Enter fullscreen mode Exit fullscreen mode

After python toc_gen.py api.md:

# API Reference

<!-- toc -->
- [Authentication](#authentication)
  - [OAuth2](#oauth2)
  - [API Keys](#api-keys)
- [Endpoints](#endpoints)
  - [Users](#users)
  - [Teams](#teams)
<!-- tocstop -->

## Authentication

### OAuth2

### API Keys

## Endpoints

### Users

### Teams
Enter fullscreen mode Exit fullscreen mode

Add a section, re-run — TOC updates. Delete a section, re-run — gone.

Features

  • Stdlib only — no pip install to run the core
  • GitHub anchors — links work on GitHub, GitLab, VS Code, Obsidian
  • Config file — set defaults in pyproject.toml or .mdtoc.yaml
  • Depth control -- --max-level 3 for top-level only
  • Dry-run -- --dry-run prints diff, writes nothing
  • CI-ready — 3 lines in GitHub Actions

GitHub Actions (auto-update TOC on push) 

name: Update TOCs
on:
  push:
    paths: ['docs/**/*.md']
  workflow_dispatch:

jobs:
  toc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install markdown-toc-generator
      - run: mdtoc docs/ -r
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'docs: sync TOCs'
Enter fullscreen mode Exit fullscreen mode

Push a doc change → TOC updates automatically.

Get it

Free (open source): Available on GitHub (search for markdown-toc-generator)

Paid ($12 — packaged with Click CLI, pyproject.toml, MIT license, ready to resell/bundle): https://contentwave2.gumroad.com/l/ddqtpv

Same core toc_gen.py in both. Paid version saves you the packaging step.

Tip jar (Solana USDC): 49NHJ5aUPpVwjMrHzgJt7pcYPCi7cxHUXVoEhgBPrAgE

Built because maintaining TOCs manually is a waste of life.

Top comments (0)