doctoc
📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.
Top Related Projects
Easy TOC creation for GitHub README.md
Quick Overview
Doctoc is a command-line tool that automatically generates and updates table of contents for Markdown files. It can be used on individual files or entire directories, and supports various Markdown flavors including GitHub and Bitbucket.
Pros
- Easy to use with a simple command-line interface
- Supports multiple Markdown flavors and file formats
- Can be integrated into CI/CD pipelines for automatic TOC generation
- Customizable output with various options for formatting and placement
Cons
- Limited to Markdown files only
- May require manual adjustments for complex document structures
- Doesn't support real-time updating of TOCs in editors
- Can potentially overwrite existing TOCs if not used carefully
Code Examples
- Generate TOC for a single file:
doctoc README.md
- Generate TOC for all Markdown files in a directory:
doctoc .
- Generate TOC with custom title and max heading level:
doctoc README.md --title "## Table of Contents" --maxlevel 3
Getting Started
To get started with Doctoc, follow these steps:
- Install Doctoc globally using npm:
npm install -g doctoc
-
Navigate to your project directory containing Markdown files.
-
Run Doctoc on a specific file or directory:
doctoc README.md
# or
doctoc .
-
Doctoc will generate and insert a table of contents into your Markdown files.
-
Commit the changes to your repository if desired.
Competitor Comparisons
Easy TOC creation for GitHub README.md
Pros of github-markdown-toc
- Written in shell script, making it more portable and easier to run without dependencies
- Can generate TOC for remote GitHub repositories without cloning
- Supports multiple input files in a single command
Cons of github-markdown-toc
- Limited to GitHub-flavored Markdown syntax
- Lacks advanced features like customizing TOC placement or ignoring specific sections
- May require additional setup on Windows systems
Code Comparison
github-markdown-toc:
#!/usr/bin/env bash
gh_toc_version="0.8.0"
gh_user_agent="gh-md-toc v$gh_toc_version"
gh_toc_load() {
local gh_url=$1
doctoc:
#!/usr/bin/env node
'use strict';
var yargs = require('yargs')
.usage('Usage: doctoc [options] <path> ... (where path is some path to a directory or Markdown file)')
Summary
github-markdown-toc is a lightweight, portable solution for generating TOCs, especially useful for remote GitHub repositories. However, it lacks some advanced features and customization options that doctoc provides. doctoc, written in JavaScript, offers more flexibility and features but requires Node.js installation. The choice between the two depends on specific project needs and environment constraints.
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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
- Usage
- Adding toc to all files in a directory and sub directories
- Update existing doctoc TOCs effortlessly
- Adding toc to individual files
- Using doctoc to generate links compatible with other sites
- Specifying location of toc
- Specifying a custom TOC title
- Specifying a maximum heading level for TOC entries
- Printing to stdout
- Usage as a
githook - Docker image
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 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 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 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
Top Related Projects
Easy TOC creation for GitHub README.md
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot