markdown-toc

# 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