doctoc

DocToc

Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites via a command line flag.

Table of Contents generated with DocToc

• Installation
• Configuring Table of Contents
  • TOC title text
  • TOC Header
  • TOC Footer
  • Min. heading level
  • Max. heading level
  • Include all headings
  • Min. ToC items
  • Pad table of contents title
  • Indentation Style
  • TOC Pragma style
• Usage
  • Configuring logging level
  • Adding toc to all files in a directory and sub directories
  • Ignoring individual files
  • Update existing doctoc TOCs effortlessly
  • Adding toc to individual files
    • Examples
  • Using doctoc to generate links compatible with other sites
    • Example
  • Specifying location of toc
  • Performing a dry run
  • Printing to stdout
  • Only update existing ToC
  • Usage as a git hook
  • Docker image

Installation

npm install -g doctoc

Configuring Table of Contents

TOC title text

Use the --title option to specify a (Markdown-formatted) custom TOC title; e.g., doctoc --title '**Contents**' . From then on, you can simply run doctoc <file> and doctoc will keep the title you specified.

Alternatively, to blank out the title, use the --notitle option. This will simply remove the title from the TOC. It is recommended to also include this argument when performing an update on an existing toc.

TOC Header

Additional text can be added to the toc header using the --toc-header-content option. The text will appear below the pragma (<!-- doctoc ... -->).

For example, running doctoc --toc-header-content 'My Header' . would produce:

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
My Header
{{toc}}
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

If you will be using the toc header option but without a toc title it is required that when updating the toc, you always include the --notitle argument.

TOC Footer

Additional text can be added to the toc header using the --toc-footer-content option. The text will appear below the pragma (<!-- doctoc ... -->).

For example, running doctoc --toc-footer-content 'My Footer' . would produce:

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
{{toc}}
My Footer
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Min. heading level

Use the --minlevel option to limit TOC entries to headings only at or above the specified level; e.g., doctoc --minlevel 2 .

By default,

• the min level used is 1 if it is not set

Note: Currently supported values are only 1 and 2.

Max. heading level

Use the --maxlevel option to limit TOC entries to headings only up to the specified level; e.g., doctoc --maxlevel 3 .

By default,

• no limit is placed on Markdown-formatted headings,
• whereas headings from embedded HTML are limited to 4 levels.

Include all headings

Use the --all option to include all headings in the TOC regardless of their location

By default,

• Only headings below the TOC will be included

Min. ToC items

Use the --mintocitems option to specify the minimum items required to be in a table of contents for it to be included in the page; e.g., doctoc --mintocitems 3 ..

By default,

• The min items is set to 1

Pad table of contents title

Use the --toc-title-padding-before option to add padding line/s above the TOC which ensures formatters such as prettier will pass; e.g., doctoc --toc-title-padding-before 1 .

NOTE: Currently it is only supported to add one line before the title.

By default,

• no padding is added above the table of contents title

In all cases there will be padding present after the title due to the toc items always having padding before the list of items.

Indentation Style

Use the --toc-items-indentation-width option to customise the indentation width e.g. doctoc --toc-items-indentation-width 4 . will set the width to 4.

By default, a width of 4 will be used if mode is gitlab or bitbucket, otherwise 2 will be used.

TOC Pragma style

The pragma is the opening and closing comment blocks to mark the location of the doctoc contents, i.e. <!-- START doctoc ... -->

The default option, legacy, produces the following:

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
{{toc}}
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

You can choose compact to make the pragma more succinct:

<!-- START doctoc -->
{{toc}}
<!-- END doctoc -->

Usage

In its simplest usage, you can pass one or more files or folders to the doctoc command. This will update the TOCs of each file specified as well as of each markdown file found by recursively searching each folder. Below are some examples.

Configuring logging level

Use the --loglevel option to configure the log level used; e.g., doctoc --loglevel warn .

By default,

• LogLevel is set to info.

Supported values are in order from lowest to highest,

• trace
• debug
• info
• warn
• error

Adding toc to all files in a directory and sub directories

Go into the directory that contains your local git project and type:

doctoc .

This will update all markdown files in the current directory and all its subdirectories with a table of content that will point at the anchors generated by the markdown parser. Doctoc defaults to using the GitHub parser, but other modes can be specified.

Ignoring individual files

In order to ignore a specific file when running doctoc on an entire directory, just add <!-- DOCTOC SKIP --> to the top of the file you wish to ignore.

Update existing doctoc TOCs effortlessly

If you already have a TOC inserted by doctoc, it will automatically be updated by running the command (rather than inserting a duplicate toc). Doctoc locates the TOC by the <!-- START doctoc --> and <!-- END doctoc --> comments, so you can also move a generated TOC to any other portion of your document and it will be updated there.

Adding toc to individual files

If you want to convert only specific files, do:

doctoc /path/to/file [...]

Examples

doctoc README.md

doctoc CONTRIBUTING.md LICENSE.md

Using doctoc to generate links compatible with other sites

In order to add a table of contents whose links are compatible other sites add the appropriate mode flag:

Available modes are:

--bitbucket bitbucket.org
--nodejs    nodejs.org
--github    github.com
--gitlab    gitlab.com
--ghost     ghost.org

Example

doctoc README.md --bitbucket

Specifying location of toc

By default, doctoc places the toc at the top of the file. You can indicate to have it placed elsewhere with the following format:

<!-- START doctoc -->
<!-- END doctoc -->

You place this code directly in your .md file. For example:

// my_new_post.md
Here we are, introducing the post. It's going to be great!
But first: a TOC for easy reference.

<!-- START doctoc -->
<!-- END doctoc -->

# Section One

Here we'll discuss...

Running doctoc will insert the toc at the specified location as illustrated below.

// my_new_post.md
Here we are, introducing the post. It's going to be great!
But first: a TOC for easy reference.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Contents**

- [Section One](#section-one)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Section One

Here we'll discuss...

Performing a dry run

Use the --dryrun option to not write changes to files but instead return an exit code of 1 to indicates files are out of date and should be updated. This is useful CI environments where you want to check if your docs are up to date as part of your build process.

Printing to stdout

You can print to stdout by using the -s or --stdout option.

This option is only applicable when specifying a single filename which doctoc is to run on. If you are specifying a folder or multiple files, the dry run option should be used instead.

Only update existing ToC

Use --update-only or -u to only update the existing ToC. That is, the Markdown files without ToC will be left untouched. It is good if you want to use doctoc with lint-staged.

Usage as a git hook

doctoc can be used as a pre-commit hook by using the following configuration:

repos:
  - repo: https://github.com/thlorenz/doctoc
    rev: ... # substitute a tagged version
    hooks:
      - id: doctoc

This will run doctoc against markdown files when committing to ensure the TOC stays up-to-date.

Docker image

There's an unofficial Docker image project for doctoc, if you'd like to use doctoc via Docker or other container based CI/CD pipeline, you can take a look at PeterDaveHello/docker-doctoc