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.

1. Insert table of contents to the README.md file in the current directory

   1docker run --rm -v .:/markdown eugenekhyst/md-toc-cli -i README.md

2. Read the manual

   1docker 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.

1. Make sure Node.js 18.x LTS or newer is installed.

2. Install md-toc-cli as a global package

   1npm i -g md-toc-cli

3. Insert table of contents to the README.md file in the current directory

   1md-toc-cli -i README.md

4. Read the manual

   1$ md-toc-cli --help

Programmatic

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

1. Make sure Node.js 18 or newer is installed.
2. Install md-toc-cli

   1npm i md-toc-cli

3. Import md-toc-cli functions

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

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

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

   1await insertOrUpdateTocInFile('README.md', {
   2  inPlace: false,
   3  suffix: 'orig',
   4  tabWidth: 2,
   5  listItemSymbol: '-',
   6  noAttribution: false,
   7});

Example

1. Create file test.md as follows

   1# Heading 1
   2
   3## Heading 2a
   4
   5### Heading 3aa
   6
   7#### Heading 4a
   8
   9##### Heading 5a
   10
   11###### Heading 6a
   12
   13### Heading 3ab
   14
   15## Heading 2b
   16
   17### Heading 3b
   18
   19#### Heading 4b
   20
   21## Heading 2c
   22
   23### Heading 3c

2. Insert table of contents to test.md and backup the original file

   1md-toc-cli test.md -i -s 'orig'

3. A backup test.md.orig is created for original file test.md.

4. A clickable table of contents is inserted into test.md

   1# <a id="0"></a>Heading 1
   2
   3<!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->
   4
   5## <a id="1"></a>Heading 2a
   6
   7### <a id="1-1"></a>Heading 3aa
   8
   9#### <a id="1-1-1"></a>Heading 4a
   10
   11##### <a id="1-1-1-1"></a>Heading 5a
   12
   13###### <a id="1-1-1-1-1"></a>Heading 6a
   14
   15### <a id="1-2"></a>Heading 3ab
   16
   17## <a id="2"></a>Heading 2b
   18
   19### <a id="2-1"></a>Heading 3b
   20
   21#### <a id="2-1-1"></a>Heading 4b
   22
   23## <a id="3"></a>Heading 2c
   24
   25### <a id="3-1"></a>Heading 3c

5. Make any change to the level 2-6 headings (e.g. delete level 5-6 headings and rename level 3 headings).

6. Update the table of contents in test.md

   1md-toc-cli -i test.md

7. The table of contents in test.md is updated according to the level 2-6 headings.