Agent skill
markdown-toc
Use when generating or updating Table of Contents in markdown files. Supports multiple files, glob patterns, configurable header levels, and various insertion modes. Triggered by "generate toc", "update toc", "table of contents", "add toc to markdown".
Stars
232
Forks
15
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/emasoft/markdown-toc
SKILL.md
Markdown Table of Contents Generator
A universal TOC generator that works with any markdown file. Supports batch processing, configurable header levels, and smart insertion.
Quick Start
bash
# Single file
python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_toc.py" README.md
# Preview without changes
python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_toc.py" --dry-run README.md
# All markdown files in docs/
python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_toc.py" docs/*.md
# Recursive processing
python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_toc.py" --recursive .
Note: You can also copy the script to your project and run it locally.
Options
| Option | Default | Description |
|---|---|---|
--dry-run |
false | Preview TOC without modifying files |
--min-level N |
2 | Minimum header level (1-6) |
--max-level N |
3 | Maximum header level (1-6) |
--title TEXT |
"Table of Contents" | Custom TOC title |
--no-title |
false | Omit TOC title |
--recursive, -r |
false | Process .md files recursively |
--insert MODE |
auto | Insertion mode: auto, top, marker |
--marker TEXT |
<!-- TOC --> |
Custom marker for marker mode |
Insertion Modes
Auto Mode (default)
Smart detection in this order:
- Replace existing
## Table of Contentssection - Insert after first
---separator (common README pattern) - Insert after YAML frontmatter
- Insert after first header
- Insert at top of file
bash
python scripts/generate_toc.py README.md
Top Mode
Insert at top of file, respecting YAML frontmatter:
bash
python scripts/generate_toc.py --insert top README.md
Marker Mode
Insert/replace between marker pairs:
bash
python scripts/generate_toc.py --insert marker README.md
In your markdown file:
markdown
<!-- TOC -->
(TOC will be inserted/updated here)
<!-- /TOC -->
Custom markers:
bash
python scripts/generate_toc.py --insert marker --marker "<!-- INDEX -->" README.md
Header Level Control
Include only H2-H3 (default):
bash
python scripts/generate_toc.py README.md
Include H1-H4:
bash
python scripts/generate_toc.py --min-level 1 --max-level 4 README.md
Include only H2:
bash
python scripts/generate_toc.py --min-level 2 --max-level 2 README.md
Batch Processing
Glob Patterns
bash
# All .md in current directory
python scripts/generate_toc.py *.md
# All .md in docs/
python scripts/generate_toc.py docs/*.md
# Specific pattern
python scripts/generate_toc.py docs/guide-*.md
Recursive
bash
# All .md files recursively
python scripts/generate_toc.py --recursive .
# Recursive in specific directory
python scripts/generate_toc.py --recursive docs/
Multiple Paths
bash
python scripts/generate_toc.py README.md CONTRIBUTING.md docs/
Output Examples
With Title (default)
markdown
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Contributing](#contributing)
Without Title
bash
python scripts/generate_toc.py --no-title README.md
markdown
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
Custom Title
bash
python scripts/generate_toc.py --title "Contents" README.md
markdown
## Contents
- [Installation](#installation)
Anchor Generation
GitHub-compatible anchors:
- Lowercase conversion
- Spaces to hyphens
- Special characters removed
- Markdown formatting stripped (
**bold**,`code`) - Emoji removed
- Multiple hyphens collapsed
| Header | Anchor |
|---|---|
## Getting Started |
#getting-started |
## **Bold** Header |
#bold-header |
## Header with code`` |
#header-with-code |
## Header #1 |
#header-1 |
Skipped Content
The script automatically skips:
- YAML frontmatter (between
---markers) - Code blocks (``` or ~~~)
- Existing "Table of Contents" headers
- Headers outside configured level range
Dry Run Preview
Always preview first with --dry-run:
bash
python scripts/generate_toc.py --dry-run README.md
Output:
[INFO] Found 1 markdown file(s)
============================================================
File: README.md
============================================================
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
...
Found 15 headers (levels 2-3)
Common Workflows
Update All Project Documentation
bash
python scripts/generate_toc.py --recursive --dry-run .
# Review output, then:
python scripts/generate_toc.py --recursive .
Standardize TOC Markers
bash
# Add markers to files, then:
python scripts/generate_toc.py --insert marker --recursive docs/
Different Levels for Different Files
bash
# Deep TOC for main README
python scripts/generate_toc.py --max-level 4 README.md
# Shallow TOC for guides
python scripts/generate_toc.py --max-level 2 docs/guides/*.md
Troubleshooting
"No headers found"
File may only have H1 headers. Use --min-level 1.
TOC inserted in wrong place
Use --insert marker with explicit markers for precise control.
Anchors don't work
Check for duplicate headers (GitHub appends -1, -2, etc.).
Portability
This script is fully portable:
- No hardcoded paths or project-specific values
- Works with any markdown file
- Standard Python 3 with no dependencies
- Can be copied to any project
Didn't find tool you were looking for?