Markdown Table of Contents Generator

Quickly generate a table of contents from a markdown file and optionally insert it inline.

Table of Contents

• Usage
  • Installation
  • Example use
  • Full usage info
• API

Usage

Installation

1# Install on a project as a dev dependancy
2npm i -D @robb_j/md-toc

Example use

You can use npx md-toc when added as a project dependancy

1# Output a table of contents for a README.md in the current directory
2npx @robb_j/md-toc
3
4# Insert a table of contents in the local README.md
5# -> Replaces inbetween <!-- toc-head --> and <!-- toc-tail -->
6npx @robb_j/md-toc -i
7
8# Output a table of contents for a different file
9npx @robb_j/md-toc -f CONTRIBUTING.md
10
11# Use a glob to process multiple files
12npx @robb_j/md-toc -f "**/*.md"
13
14# Test a glob to see what it matches
15npx @robb_j/md-toc -f "**/*.md" --dry-run

Full usage info

Usage: @robb_j/md-toc [options]

A tool for generating a table of contents for readmes

Options:
  -V, --version          output the version number
  -f --file [README.md]  specify where the markdown file(s) you want to process are, accepts a filename or a glob (default: "README.md")
  -i --inline [false]    edit the table of contents inline, it replaces between '<!-- toc-head -->' and <!-- toc-tail --> (default: false)
  --dry-run [false]      perform a dry run, useful for testing your glob
  -h, --help             output usage information

API

You can use this programmatically in node by importing the module, see cli.js for detailed usage.

1const { tableOfContents, headTag, tailTag } = require('@robb_j/md-toc')
2
3// filename: string
4// inline: boolean
5tableOfContents(filename, inline)

Development

1# Run the cli when you have the repo checked out
2# NOTE: Make sure not to process this readme as it has toc-head/tail comments in for documentation only
3node src/cli.js # ...

Future work

• Take file pattern as an argument rather than an option, i.e. md-toc <...pattern>, perhaps as a varadic argument

---

This repo was set up with robb-j/node-base