markdown-toc-gen

1.2.0 verified Sat Apr 25 auth: no javascript

A CLI tool to generate, update, check, and test table of contents in Markdown files, with focus on conformity with Prettier formatting (hyphens as bullet list). Current stable version 1.2.0. It handles duplicate headings, ignores code blocks, and supports multiple files via glob patterns. Differs from similar tools by being Prettier-compliant, excluding h1 headings by default, and offering a dry-run mode. The tool requires '' and '' markers in Markdown files.

Common errors

error Error: Cannot find module 'markdown-toc-gen' ↓

cause Trying to import as a library instead of using CLI.

fix

Use npx or install globally: npx markdown-toc-gen insert README.md

error Error: No toc markers found ↓

cause Missing '' and '' markers in the file.

fix

Add the required markers to your Markdown file.

error Error: ENOENT: no such file or directory ↓

cause Specified file path does not exist.

fix

Check the file path and ensure it exists.

error Error: Cannot read property 'map' of undefined ↓

cause File is empty or not valid Markdown.

fix

Ensure the file contains at least some headings.

Warnings

gotcha The tool excludes h1 headings by default; only h2 through h6 are included in the TOC. ↓

fix Use --max-depth to include h1 if desired, e.g., --max-depth 1

gotcha Markers '' and '' must be separated by at least one newline from other content. ↓

fix Ensure there is a blank line before and after the marker lines.

gotcha Node.js version 12 or higher is required; lower versions may produce errors. ↓

fix Upgrade Node.js to >=12

Install

npm install markdown-toc-gen

yarn add markdown-toc-gen

pnpm add markdown-toc-gen

Imports

markdown-toc-gen
wrong
```
import markdownTocGen from 'markdown-toc-gen'
```
correct
```
npx markdown-toc-gen insert README.md
```
This is a CLI tool, not a library. Use via npx or global install.

Quickstart

Shows basic usage: install, add TOC markers, insert TOC, and check TOC freshness.

# Install globally or use npx
npm install -g markdown-toc-gen

# Add markers to your README.md
# <!-- toc -->
# <!-- tocstop -->

# Generate TOC
markdown-toc-gen insert README.md

# Check if TOC is up-to-date (useful in CI)
markdown-toc-gen check README.md