tocgenie

A fast CLI tool that generates a table of contents for markdown files — with anchor links compatible with GitHub, GitLab, Bitbucket, or any custom platform. Works out of the box with any git repository.

Generated with tocgenie

• Installation
• Quick Start
• Real World Examples
  • Single File
  • Entire Repository
  • In-Place Insertion
  • CI / Automation
  • Using in Another Project
• Options
• Platform Flavors
• Development
• Project Structure

Installation

Clone and build:

git clone https://github.com/smarkstrife/tocgenie.git
cd tocgenie
npm install
npm run build

Install globally (run tocgenie from anywhere):

npm install -g .

Use as a dev dependency in another project:

npm install --save-dev /path/to/tocgenie

Quick Start

# Generate TOC for a single file
tocgenie README.md

# Insert TOC directly into a file (add markers first — see below)
tocgenie --insert README.md

# Generate TOC for all tracked .md files in a git repo
tocgenie

Real World Examples

Single File

Generate a TOC and print to stdout:

tocgenie README.md

Output:

- [Installation](#installation)
- [Usage](#usage)
  - [Options](#options)
  - [Examples](#examples)
- [Contributing](#contributing)

Save the TOC to a separate file:

tocgenie -O toc.md README.md

Real file example — given a file story.md with this structure:

# The Last Compiler
## Prologue
## Chapter 1: The Bug
### The Discovery
### The Aftermath
## Chapter 2: The Fix
## Epilogue

Running:

tocgenie --no-git story.md

Produces:

- [The Last Compiler](#the-last-compiler)
  - [Prologue](#prologue)
  - [Chapter 1: The Bug](#chapter-1-the-bug)
    - [The Discovery](#the-discovery)
    - [The Aftermath](#the-aftermath)
  - [Chapter 2: The Fix](#chapter-2-the-fix)
  - [Epilogue](#epilogue)

Skip the top-level heading and use an ordered list:

tocgenie --no-git --min-level 2 --ordered story.md

Output:

1. [Prologue](#prologue)
1. [Chapter 1: The Bug](#chapter-1-the-bug)
   1. [The Discovery](#the-discovery)
   1. [The Aftermath](#the-aftermath)
1. [Chapter 2: The Fix](#chapter-2-the-fix)
1. [Epilogue](#epilogue)

Entire Repository

Scan all git-tracked .md files in the current repo:

tocgenie

Include files not yet committed to git:

tocgenie --include-untracked

Not in a git repo? Walk the filesystem instead:

tocgenie --no-git docs/

In-Place Insertion

This is the most common workflow. Add two marker comments anywhere in your markdown file:

## Table of Contents

<!-- toc -->
<!-- /toc -->

## Introduction

Then run:

tocgenie --insert README.md

tocgenie replaces everything between the markers with the generated TOC. Re-running the command is safe — it always replaces the existing content, never duplicates it.

Custom marker:

tocgenie --insert --marker "<!-- contents -->" README.md

CI / Automation

Keep your TOC up to date automatically. Add tocgenie as a dev dependency and a script in package.json:

{
  "scripts": {
    "toc": "tocgenie --insert README.md"
  },
  "devDependencies": {
    "tocgenie": "file:../tocgenie"
  }
}

Then run it as part of your workflow:

npm run toc

Or in a GitHub Actions workflow:

- name: Update TOC
  run: npx tocgenie --insert README.md

Using in Another Project

Option 1 — Global install (recommended for personal use):

npm install -g /path/to/tocgenie
tocgenie --insert README.md   # works in any directory

Option 2 — Local dev dependency:

npm install --save-dev /path/to/tocgenie

Add to package.json:

"scripts": {
  "toc": "tocgenie --insert README.md"
}

Option 3 — One-off via node directly:

node /path/to/tocgenie/dist/cli.js --no-git README.md

Options

| Flag | Short | Default | Description | |---|---|---|---| | --flavor <flavor> | -f | github | Anchor flavor: github, gitlab, bitbucket, generic | | --min-level <n> | | 1 | Minimum heading level to include | | --max-level <n> | | 6 | Maximum heading level to include | | --ordered | -o | false | Use ordered (1.) list markers | | --no-link | | false | Omit anchor links (plain text outline) | | --indent <n> | | 2 | Spaces per indent level | | --output <file> | -O | stdout | Write TOC to a file | | --insert | -i | false | Insert/replace TOC in-place between markers | | --marker <marker> | | <!-- toc --> | Marker used for in-place insertion | | --include-untracked | | false | Include untracked (but not gitignored) files | | --no-git | | false | Walk the filesystem instead of using git | | --anchor-prefix <prefix> | | "" | Custom prefix for generic flavor | | --anchor-strip-regex <regex> | | none | Custom strip regex for generic flavor | | [files...] | | all .md | Explicit files or globs to process |

Platform Flavors

Different platforms generate anchor slugs differently. Use --flavor to match your target platform.

| Flavor | Example heading | Generated anchor | |---|---|---| | github (default) | ## My Heading | #my-heading | | gitlab | ## My Heading | #my-heading | | bitbucket | ## My Heading | #markdown-header-my-heading | | generic | configurable via --anchor-prefix / --anchor-strip-regex | custom |

Examples:

tocgenie -f gitlab README.md
tocgenie -f bitbucket README.md
tocgenie -f generic --anchor-prefix "section-" README.md

Development

npm test              # run all tests
npm run test:watch    # watch mode
npm run build         # compile TypeScript
npm run dev -- --no-git README.md   # run without building

Project Structure

src/
├── cli.ts        Entry point and argument parsing
├── parser.ts     Markdown heading extraction
├── anchor.ts     Anchor/slug generation per platform flavor
├── toc.ts        TOC assembly and in-place insertion
├── git.ts        Git-aware and filesystem file discovery
└── types.ts      Shared type definitions
tests/
├── parser.test.ts
├── anchor.test.ts
├── toc.test.ts
└── fixtures/     Sample .md files used in tests

Author: Shikhar Srivastava