md-toc

Generate a GitHub compatible table of contents from headings in a markdown file.

Table of contents

• Motivation
• Installation
• Usage
  • Usage with lint-staged
  • Usage as a CLI
• Debugging
• Contributing

Motivation

I wanted something for myself that does exactly what I need it to do and exposes all the levers that I need. Also, I specifically wanted a CLI that can run in a pre-commit hook (via husky + lint-staged) before prettier --write for markdown files so that I never have another piece of documentation without a table of contents!

Installation

npm install -D @zeusdeux/md-toc

Usage

Usage with lint-staged

Add the following line to the "lint-staged" config

"lint-staged": {
  "*.md": "md-toc --write",
}

It is recommended that you run prettier after md-toc. For example —

"lint-staged": {
  "*.md": "md-toc --write",
  "*.{js,cjs,mjs,ts,json,yaml,md}": "prettier --write"
}

Usage as a CLI

Usage: md-toc [options] <file or stdin>

Options:
  -w, --write        Write changes to the input file  [boolean] [default: false]
  -a, --insert-under Heading to insert the table of contents under      [string]
  -d, --debug        Print debug logs to stderr       [boolean] [default: false]
  -v, --version      Show cli version                                  [boolean]
  -h, --help         Show help                                         [boolean]

Examples:
  md-toc --write Readme.md           Generate a table of contents from headings
                                     in Readme.md, insert them under a heading
                                     name "Table of Contents", "toc" or
                                     "table-of-contents" (all case insensitive)
                                     in Readme.md and write the file to disk
  md-toc Readme.md                   Same as the --write option but the output
                                     is written to stdout and Readme.md is left
                                     as is
  md-toc -a "Contents" -w Readme.md  Same as --write but the table of contents
                                     is inserted under the first heading named
                                     "Contents"

Debugging

If you run into problems and want to open an issue here, please run the cli with --debug and put the output in the issue. Do redact PII from the debug info before pasting into the issue.

Contributing

The package manager used is pnpm so please use that and don't commit a package-lock.json. Also, before starting development, run nvm use in the folder where you clone this repository.

Other than that, it is a fairly tiny codebase. Feel free to clone, edit and open a PR.

To test your changes locally, run pnpm link --global and assuming you are using nvm, this should make md-toc available as a command in your shell.