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".

View SKILL.md on GitHub Repository
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:

  1. Replace existing ## Table of Contents section
  2. Insert after first --- separator (common README pattern)
  3. Insert after YAML frontmatter
  4. Insert after first header
  5. 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results