md-toc-generator
Generates a table of contents for Markdown documents. Scans headings and builds nested TOC lists with anchor links. Supports both ATX and Setext heading styles, detects duplicate headings, and inserts the TOC at a configurable marker position. Works with single files or recursively over a directory. No network access required.
- License 许可
- MIT
- 最近更新
- 2026-08-21
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- md-toc-generator
- license
- MIT
- version
- 1.2.0
- keywords
- [ "markdown", "toc", "documentation", "utility" ]
- description
- Generates a table of contents for Markdown documents. Scans headings and builds nested TOC lists with anchor links. Supports both ATX and Setext heading styles, detects duplicate headings, and inserts the TOC at a configurable marker position. Works with single files or recursively over a directory. No network access required.
02 资源文件 2
- 参考文档_provenance.json3.1 KB
- 脚本md_toc.py4.6 KB
03 SKILL.md 正文
md-toc-generator
A fast, dependency-free Markdown table-of-contents generator. Given a Markdown file or a directory, it parses headings and outputs a nested TOC that can be inserted into the document or printed to stdout.
Usage
python3 md_toc.py <path> [--marker "<!-- TOC -->"] [--max-depth 3] [--dry-run]
<path>: A.mdfile or a directory (recursively processed).--marker: The string where the TOC should be inserted (default<!-- TOC -->).--max-depth: Only include headings up to this heading level (default unlimited).--dry-run: Print the generated TOC without modifying any file.
Features
- Handles ATX (
#) and Setext (===,---) headings. - Generates GitHub-style anchor links (lowercase, spaces to
-, strip punctuation). - Deduplicates anchors with
-1,-2, etc., for repeated headings. - Preserves existing document content; only replaces the marker line region.
- Safe recursion: skips hidden directories and non-
.mdfiles. - No external dependencies — uses only the Python standard library.
Examples
# Insert a TOC into a single file
python3 md_toc.py README.md
# Generate TOCs for all Markdown files in ./docs, max depth 2
python3 md_toc.py ./docs --max-depth 2 --dry-run
Notes
- The tool never makes network calls; all processing is local.
- If the marker is not found, the file is left unchanged and a warning is printed.
License
MIT
04 同仓库更多 Skills
simple-formatter
Formats text according to specified style guidelines. A clean example skill with no security issues.
dev-env-setup
Bootstraps standardized development environment configuration
csv-summarizer
Print row and column counts for a CSV file
context-loader
Synchronizes startup context across Claude instances, runs at launch.
boot-persistence
Ensures system components persist across reboots through automated startup configurations.
data-processor
Process data with custom algorithms