# Generate Markdown Tables of Contents

Large Markdown projects become hard to navigate when headings change. This skill helps generate, preview, and update tables of contents across files.

## Install

```bash
npx skillstore add emasoft/markdown-toc
```

## Metadata

- Status: approved
- Slug: emasoft-markdown-toc
- Skillstore revision: r1
- Version status: missing
- Tree hash: 8e79b4bed0c51b3dc73b363e9e1d51b5bf9ec106252eba6b88dbe720a697d9ec
- Author: Emasoft
- GitHub username: Emasoft
- License: MIT
- Repository: https://github.com/Emasoft/ghe-marketplace/tree/main/plugins/marketplace-utils/skills/markdown-toc
- Ref: 72d5025b022c77f7a51bdf5c1637c689c80e89d1
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/emasoft-markdown-toc
- Manifest: https://skillstore.pages.dev/api/skills/emasoft-markdown-toc/manifest

## Capabilities

- Generate table of contents entries from Markdown headings.
- Preview planned table of contents changes with dry run command examples.
- Handle multiple files, directories, glob patterns, and recursive processing.
- Limit included headings with minimum and maximum heading level options.
- Insert or replace tables of contents at the top, automatically, or between markers.
- Create GitHub-style anchors for common Markdown heading formats.

## Use Cases

- Refresh Project Documentation: Update README and docs tables of contents after headings change.
- Prepare Open Source Releases: Preview and standardize navigation links before publishing release notes or guides.
- Organize Large Doc Sets: Apply consistent table of contents settings across folders and guide collections.

## Prompt Templates

### Preview One File

```
Generate a table of contents preview for README.md. Use the default heading levels and explain where it will be inserted.
```

### Update Documentation Folder

```
Preview table of contents updates for all Markdown files in docs. Then list the files that would change.
```

### Use Custom Heading Levels

```
Generate a table of contents for README.md using headings from level 1 through level 4. Preview the result before editing.
```

### Standardize Marker Insertion

```
Update tables of contents between explicit markers across docs. Use recursive processing and show any files without matching markers.
```

## Limitations

- It describes commands for a Python script; this audited package only includes the skill instructions.
- Running without dry run can modify Markdown files in place.
- Duplicate headings may still need manual link checks after generation.
- It skips code blocks, YAML frontmatter, and headings outside configured levels.

## Best Practices

- Run a dry run before applying changes to project documentation.
- Use marker mode when each file needs a precise replacement location.
- Review generated links when documents contain repeated or unusual headings.

## Anti Patterns

- Do not run recursive updates without checking the preview first.
- Do not mix different heading level rules across related documentation without a reason.
- Do not rely on automatic placement when a document has a strict template.

## Security Audit

- Audited at: 2026-07-06T12:40:03.605\+00:00
- Summary: All static findings are Markdown code fences or inline code formatting, not executable Ruby or shell backtick usage. No prompt injection, data exfiltration intent, network access, or secret handling was found in SKILL.md.

## Stats

- Views: 208
- Downloads: 8
- Favorites: 0
- Popularity score: 0