Table of contents generator for Markdown

Introduction
Usage
- Docker
- npm
- Programmatic
Example

Introduction

Automatically insert or update a clickable table of contents (TOC) into your Markdown documents based on its headings using CLI or JavaScript module with the perfect support for README.md files on GitHub.

md-toc-cli creates table of contents from level 2-6 headings (e.g., ## Heading, ### Heading etc.) and inserts it after level 1 heading or at the beginning of the file. Zero or one level 1 heading is expected (e.g., # Heading).

HTML anchor elements are added to level 1-6 headings to make table of content items clickable, e.g. <a id="..."></a>.

Anchor at level 1 heading allows creating Back to top links as [Back to top](#0).

Usage

md-toc-cli is available as npm package and Docker image.

Docker

When running md-toc-cli using Docker, mount the directory containing the Markdown files as a volume.

Insert table of contents to the README.md file in the current directory
```
docker run --rm -v .:/markdown eugenekhyst/md-toc-cli -i README.md
```

Read the manual

docker run --rm -v .:/markdown eugenekhyst/md-toc-cli --help

md-toc-cli [file]

Automatically insert or update a clickable table of contents (TOC) into your
Markdown documents based on its headings (levels 2-6).

Positionals:
  file  Markdown file for inserting or updating table of contents in
                                                 [string] [default: "README.md"]

Options:
      --version           Show version number                          [boolean]
      --help              Show help                                    [boolean]
  -i, --in-place          Edit file in place          [boolean] [default: false]
  -s, --suffix            The extension of a backup copy. If no extension is
                          supplied, the original file is overwritten without
                          making a backup. This option implies -i.      [string]
  -t, --tab-width         The number of spaces per indentation-level
                                                           [number] [default: 2]
  -l, --list-item-symbol  Symbol used in front of line items to create an
                          unordered list
                                [string] [choices: "-", "*", "+"] [default: "-"]
  -n, --no-attribution    Do not add an attribution "Table of contents is made
                          with ..."                   [boolean] [default: false]

npm

When running md-toc-cli using Node.js, install the package globally for convenience.

Make sure Node.js 18.x LTS or newer is installed.
Install md-toc-cli as a global package
```
npm i -g md-toc-cli
```
Insert table of contents to the README.md file in the current directory
```
md-toc-cli -i README.md
```
Read the manual
```
$ md-toc-cli --help
```

Programmatic

md-toc-cli can be used as a library in JavaScript and TypeScript projects.

Make sure Node.js 18 or newer is installed.
Install md-toc-cli
```
npm i md-toc-cli
```

Import md-toc-cli functions

import { insertOrUpdateToc, insertOrUpdateTocInFile } from 'md-toc-cli';

Programmatically insert or update the table of contents in a Markdown string or file

insertOrUpdateToc(markdownContent, {
  tabWidth: 2,
  listItemSymbol: '-',
  noAttribution: false,
});

await insertOrUpdateTocInFile('README.md', {
  inPlace: false,
  suffix: 'orig',
  tabWidth: 2,
  listItemSymbol: '-',
  noAttribution: false,
});

Example

Create file test.md as follows

# Heading 1

## Heading 2a

### Heading 3aa

#### Heading 4a

##### Heading 5a

###### Heading 6a

### Heading 3ab

## Heading 2b

### Heading 3b

#### Heading 4b

## Heading 2c

### Heading 3c

Insert table of contents to test.md and backup the original file
```
md-toc-cli test.md -i -s 'orig'
```
A backup test.md.orig is created for original file test.md.

A clickable table of contents is inserted into test.md

# <a id="0"></a>Heading 1

- [Heading 2a](#1)
  - [Heading 3aa](#1-1)
    - [Heading 4a](#1-1-1)
      - [Heading 5a](#1-1-1-1)
        - [Heading 6a](#1-1-1-1-1)
  - [Heading 3ab](#1-2)
- [Heading 2b](#2)
  - [Heading 3b](#2-1)
    - [Heading 4b](#2-1-1)
- [Heading 2c](#3)
  - [Heading 3c](#3-1)

<!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->

## <a id="1"></a>Heading 2a

### <a id="1-1"></a>Heading 3aa

#### <a id="1-1-1"></a>Heading 4a

##### <a id="1-1-1-1"></a>Heading 5a

###### <a id="1-1-1-1-1"></a>Heading 6a

### <a id="1-2"></a>Heading 3ab

## <a id="2"></a>Heading 2b

### <a id="2-1"></a>Heading 3b

#### <a id="2-1-1"></a>Heading 4b

## <a id="3"></a>Heading 2c

### <a id="3-1"></a>Heading 3c

Make any change to the level 2-6 headings (e.g. delete level 5-6 headings and rename level 3 headings).
Update the table of contents in test.md
```
md-toc-cli -i test.md
```
The table of contents in test.md is updated according to the level 2-6 headings.