Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time


This is a golang based implementation of the github-markdown-toc tool.

The advantages of this implementation:

  • no dependencies (no need curl, wget, awk, etc.)
  • cross-platform (support for Windows, Mac OS, etc.)
  • regexp for parsing TOC
  • parallel processing of multiple documents

Attention: gh-md-toc is able to work properly only if your machine is connected to the Internet.

Table of Contents

Created by gh-md-toc


Precompiled binaries

See the releases page, "Downloads" section:

For example:

$ wget
$ tar xzvf gh-md-toc.linux.amd64.tgz
$ ./gh-md-toc --version

Compiling from source

You need golang installed is your OS:

$ make build
$ ./gh-md-toc --help
usage: gh-md-toc [<flags>] [<path>...]

  --help     Show help (also see --help-long and --help-man).
  --version  Show application version.
  --depth    How many levels of headings to include. Defaults to 0 (all)

  [<path>]  Local path or URL of the document to grab TOC

Homebew (Mac only)

$ brew install github-markdown-toc


$ make test
coverage: 28.8% of statements
ok      _~/projects/my/github-toc.go    0.003s



Here's an example of TOC creating for markdown from STDIN:

➥ cat ~/projects/Dockerfile.vim/ | ./gh-md-toc
  * [Dockerfile.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
        * [OR using Pathogen:](#or-using-pathogen)
        * [OR using Vundle:](#or-using-vundle)
  * [License](#license)

Local files

Here's an example of TOC creating for a local

➥ ./gh-md-toc ~/projects/Dockerfile.vim/                                                                                                                                                Вс. марта 22 22:51:46 MSK 2015

Table of Contents

  * [Dockerfile.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
        * [OR using Pathogen:](#or-using-pathogen)
        * [OR using Vundle:](#or-using-vundle)
  * [License](#license)

Remote files

And here's an example, when you have a like this:

And you want to generate TOC for it.

There is nothing easier:

➥ ./gh-md-toc

Table of Contents

  * [envirius](#envirius)
    * [Idea](#idea)
    * [Features](#features)
  * [Installation](#installation)
  * [Uninstallation](#uninstallation)
  * [Available plugins](#available-plugins)
  * [Usage](#usage)
    * [Check available plugins](#check-available-plugins)
    * [Check available versions for each plugin](#check-available-versions-for-each-plugin)
    * [Create an environment](#create-an-environment)
    * [Activate/deactivate environment](#activatedeactivate-environment)
      * [Activating in a new shell](#activating-in-a-new-shell)
      * [Activating in the same shell](#activating-in-the-same-shell)
    * [Get list of environments](#get-list-of-environments)
    * [Get current activated environment](#get-current-activated-environment)
    * [Do something in environment without enabling it](#do-something-in-environment-without-enabling-it)
    * [Get help](#get-help)
    * [Get help for a command](#get-help-for-a-command)
  * [How to add a plugin?](#how-to-add-a-plugin)
    * [Mandatory elements](#mandatory-elements)
      * [plug_list_versions](#plug_list_versions)
      * [plug_url_for_download](#plug_url_for_download)
      * [plug_build](#plug_build)
    * [Optional elements](#optional-elements)
      * [Variables](#variables)
      * [Functions](#functions)
    * [Examples](#examples)
  * [Example of the usage](#example-of-the-usage)
  * [Dependencies](#dependencies)
  * [Supported OS](#supported-os)
  * [Tests](#tests)
  * [Version History](#version-history)
  * [License](#license)
  * [README in another language](#readme-in-another-language)

That's all! Now all you need — is copy/paste result from console into original

And here is a result:

Multiple files

It supports multiple files as well:

➥ ./gh-md-toc \ \ \ \

  * [Hello world](

  * [Control Flow](
    * [If](
    * [Loops](
    * [For loops](
    * [Switch/Match](
    * [Method call](

  * [Primitive Types and Operators](

  * [Unique Pointers](

Processing of multiple documents is in parallel mode since version 0.4.0 You can use (old) serial mode by passing option --serial in the console:

$ ./gh-md-toc --serial ...


time (./gh-md-toc --serial ../envirius/ ../github-toc/ > /dev/null)

real    0m1.200s
user    0m0.040s
sys     0m0.004s
time (./gh-md-toc ../envirius/ ../github-toc/ > /dev/null)

real    0m0.784s
user    0m0.036s
sys     0m0.004s


You can easily combine both ways:

➥ ./gh-md-toc \
    ~/projects/Dockerfile.vim/ \

  * [Dockerfile.vim](~/projects/Dockerfile.vim/
  * [Screenshot](~/projects/Dockerfile.vim/
  * [Installation](~/projects/Dockerfile.vim/
        * [OR using Pathogen:](~/projects/Dockerfile.vim/
        * [OR using Vundle:](~/projects/Dockerfile.vim/
  * [License](~/projects/Dockerfile.vim/

  * [sitemap.js](
    * [Installation](
    * [Usage](
    * [License](

Created by [gh-md-toc](


Use --depth=INT to control how many levels of headers to include in the TOC

➥ ./gh-md-toc --depth=1 ~/projects/Dockerfile.vim/

Table of Contents

  * [Dockerfile\.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
  * [License](#license)

No escape

➥ ./gh-md-toc ~/projects/my/Dockerfile.vim/ | grep Docker
* [Dockerfile\.vim](#dockerfilevim)

➥ ./gh-md-toc --no-escape ~/projects/my/Dockerfile.vim/ | grep Docker
* [Dockerfile.vim](#dockerfilevim)

Github token

All your tokents are here.

Example for cli argument:

➥ ./gh-md-toc --depth=1 --token=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563

Table of Contents

* [github\-markdown\-toc](#github-markdown-toc)
* [Table of Contents](#table-of-contents)
* [Installation](#installation)
* [Tests](#tests)
* [Usage](#usage)
* [LICENSE](#license)

Example for environment variable:

➥ GH_TOC_TOKEN=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 ./gh-md-toc --depth=1

Table of Contents

* [github\-markdown\-toc](#github-markdown-toc)
* [Table of Contents](#table-of-contents)
* [Installation](#installation)
* [Tests](#tests)
* [Usage](#usage)
* [LICENSE](#license)

Bash/ZSH auto-complete

Just add a simple command into your ~/.bashrc or ~/.zshrc:

# for zsh
eval "$(gh-md-toc --completion-script-zsh)"

# for bash
eval "$(gh-md-toc --completion-script-bash)"

Alpine Linux

Alpine Linux uses musl instead of glibc by default. If you install binutils and run…

apk add binutils && \
readelf -l /path/to/gh-md-toc

…you'll see that it relies on /lib64/ as its interpreter. You can solve this by installing libc6-compat alongside downloading the Linux amd64 build.

apk add libc6-compat


See LICENSE file.

You can’t perform that action at this time.