doctoc vs markdown-toc
Table of Contents Generators for Markdown Files
Search packages..
doctocmarkdown-toc
Table of Contents Generators for Markdown Files

Table of Contents (TOC) generators for Markdown files are tools that automatically create a structured list of links to the headings within a Markdown document. This is particularly useful for long documents, as it provides readers with a quick way to navigate to specific sections. Both doctoc and markdown-toc are popular npm packages that can scan a Markdown file, identify its headings (h1, h2, h3, etc.), and insert a TOC at a specified location. They can be configured to update the TOC automatically, ensuring it stays in sync with the document's structure.

Npm Package Weekly Downloads Trend
3 Years
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
doctoc187,4124,38720.8 kB72-MIT
markdown-toc117,3121,735-918 years agoMIT
Feature Comparison: doctoc vs markdown-toc

Customization

  • doctoc:

    doctoc offers limited customization, primarily focusing on automatically generating a TOC based on the document's headings. It allows for some configuration via command-line options, but it is designed to be simple and straightforward, with minimal setup required.

  • markdown-toc:

    markdown-toc provides extensive customization options, including the ability to specify which heading levels to include, customize the link format, and even use templates for the TOC. This makes it much more flexible for users who need to tailor the TOC to fit specific requirements.

Integration

  • doctoc:

    doctoc is designed to be run as a standalone command-line tool, making it easy to integrate into scripts or run manually as needed. It does not require any special setup or configuration to use, which makes it very accessible for quick tasks.

  • markdown-toc:

    markdown-toc can be integrated into build processes and supports being used as a library within other Node.js applications. This makes it a better choice for projects that need to automate TOC generation as part of a larger workflow.

Installation and Usage

  • doctoc:

    doctoc is easy to install and use. Simply add it to your project via npm and run it from the command line to generate a TOC. It automatically detects where to insert the TOC and updates it as needed.

  • markdown-toc:

    markdown-toc also installs easily via npm. It can be used from the command line or imported as a module in your JavaScript code. Its API allows for programmatic TOC generation, which is useful for more complex applications.

Example Code

  • doctoc:

    Example of using doctoc to generate a TOC:

    npx doctoc README.md
  • markdown-toc:

    Example of using markdown-toc to generate a TOC:

    npx markdown-toc README.md -i
How to Choose: doctoc vs markdown-toc
  • doctoc:

    Choose doctoc if you want a simple, automated solution that inserts a TOC with minimal configuration. It is particularly user-friendly and works well for projects where you want to quickly add a TOC without much setup.

  • markdown-toc:

    Choose markdown-toc if you need more customization options, such as the ability to specify the heading levels, customize the TOC format, or integrate it into your build process. It is ideal for projects that require more control over how the TOC is generated.

Similar Npm Packages to doctoc

doctoc is a command-line tool designed to automatically generate a table of contents for Markdown files. It scans the document for headings and creates a structured list that links to each section, making it easier for readers to navigate lengthy documents. This tool is particularly useful for developers and writers who frequently work with Markdown and want to enhance the usability of their documents without manually creating and updating the table of contents.

While doctoc is a robust solution for generating tables of contents, there are alternatives available in the ecosystem. One notable alternative is:

  • markdown-toc, which is another tool for generating a table of contents for Markdown files. It provides similar functionality to doctoc, allowing users to create a structured list of links based on the headings in their Markdown documents. markdown-toc can be integrated into build processes or used as a standalone command-line tool. It offers flexibility in terms of customization and can be easily configured to suit different Markdown styles and preferences.

For a detailed comparison of these two packages, you can visit: Comparing doctoc vs markdown-toc.

README for doctoc

DocToc Node.js CI

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

npm install -g 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.

Adding toc to all files in a directory and sub directories

Go into the directory that contains you 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 that location.

Specifying a custom TOC title

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

Specifying a maximum heading level for TOC entries

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.

Printing to stdout

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

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

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.