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.
Created by gh-md-toc
See the releases page, "Downloads" section:
For example:
$ wget https://github.com/ekalinin/github-markdown-toc.go/releases/download/v2.0.1/gh-md-toc.linux.amd64.tgz
$ tar xzvf gh-md-toc.linux.amd64.tgz
gh-md-toc
$ ./gh-md-toc --version
2.0.1
os: linux
arch: amd64
go: go1.26.5The first line is the bare version number, so scripts that parse gh-md-toc --version will continue to work.
You need Go 1.26 or newer installed in your OS:
$ make build
$ ./gh-md-toc --help
usage: gh-md-toc [<flags>] [<path>...]
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
--serial Grab TOCs in the serial mode
--hide-header Hide TOC header
--hide-footer Hide TOC footer
--start-depth=0 Start including from this level. Defaults to 0 (include all levels)
--depth=0 How many levels of headings to include. Defaults to 0 (all)
--no-escape Do not escape chars in sections
--token=TOKEN GitHub personal token
--indent=2 Indent space of generated list
--debug Show debug info
--github-url="https://api.github.com"
GitHub URL. Default: https://api.github.com
--re-version=2024-03
RegExp version. Default: 2024-03
--insert Insert the TOC into the file, between <!--ts--> and <!--te-->. Local files only
--no-backup Do not keep a backup copy of the file. Requires --insert
--skip-header Ignore everything up to <!--te--> when building the TOC
--version Show application version.
Args:
[<path>] Local path or URL of the document to grab TOC. Read MD from stdin if not entered.You need Go 1.26 or newer installed in your OS:
go install "github.com/ekalinin/github-markdown-toc.go/cmd/gh-md-toc@latest"$ brew install github-markdown-toc$ docker run --rm -v "$PWD:/data" -w /data \
ghcr.io/ekalinin/github-markdown-toc.go:latest README.mdPass a token with -e GH_TOC_TOKEN=... when you hit the GitHub API rate limit.
The image runs as a non-root user, so --insert against a bind-mounted file fails
with a permission error unless you also pass --user "$(id -u):$(id -g)".
$ make test
coverage: 28.8% of statements
ok _~/projects/my/github-toc.go 0.003sHere's an example of TOC creating for markdown from STDIN:
➥ cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc
* [Dockerfile.vim](#dockerfilevim)
* [Screenshot](#screenshot)
* [Installation](#installation)
* [OR using Pathogen:](#or-using-pathogen)
* [OR using Vundle:](#or-using-vundle)
* [License](#license)Here's an example of TOC creating for a local README.md:
➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md Вс. марта 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)And here's an example, when you have a README.md like this:
And you want to generate TOC for it.
There is nothing easier:
➥ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
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 README.md.
And here is a result:
It supports multiple files as well:
➥ ./gh-md-toc \
https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md \
https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md \
https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md \
https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md
* [Hello world](https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md#hello-world)
* [Control Flow](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#control-flow)
* [If](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#if)
* [Loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#loops)
* [For loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#for-loops)
* [Switch/Match](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#switchmatch)
* [Method call](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#method-call)
* [Primitive Types and Operators](https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md#primitive-types-and-operators)
* [Unique Pointers](https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md#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 ...Timings:
➥ time (./gh-md-toc --serial README.md ../envirius/README.ru.md ../github-toc/README.md > /dev/null)
real 0m1.200s
user 0m0.040s
sys 0m0.004s➥ time (./gh-md-toc README.md ../envirius/README.ru.md ../github-toc/README.md > /dev/null)
real 0m0.784s
user 0m0.036s
sys 0m0.004sYou can easily combine both ways:
➥ ./gh-md-toc \
~/projects/Dockerfile.vim/README.md \
https://github.com/ekalinin/sitemap.s/blob/master/README.md
* [Dockerfile.vim](~/projects/Dockerfile.vim/README.md#dockerfilevim)
* [Screenshot](~/projects/Dockerfile.vim/README.md#screenshot)
* [Installation](~/projects/Dockerfile.vim/README.md#installation)
* [OR using Pathogen:](~/projects/Dockerfile.vim/README.md#or-using-pathogen)
* [OR using Vundle:](~/projects/Dockerfile.vim/README.md#or-using-vundle)
* [License](~/projects/Dockerfile.vim/README.md#license)
* [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/master/README.md#sitemapjs)
* [Installation](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation)
* [Usage](https://github.com/ekalinin/sitemap.js/blob/master/README.md#usage)
* [License](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)gh-md-toc can write the TOC directly into a document instead of only printing it.
Add a marker line containing <!--ts--> where the TOC should start, and below it a
marker line containing <!--te--> where it should end - each marker needs its own
line, with nothing else on it besides surrounding whitespace. Then run:
$ ./gh-md-toc --insert README.mdEverything between the two markers is replaced with the generated TOC; the markers
themselves and the rest of the document are left untouched. The Table of Contents
heading is not written into the file, only the list itself.
--insert only works on local files. A remote URL passed alongside --insert is
reported as not local and left unmodified, instead of failing the whole run.
An inserted TOC always links with bare anchors (#section), even when several files
are passed at once. GitHub resolves relative links against the document's own
directory, so prefixing the links with the document's path would break them.
Before rewriting the file, a backup copy is kept next to it, named
<file>.orig.<timestamp>. Pass --no-backup to skip the backup; that flag requires
--insert and is rejected on its own.
Unless --hide-footer is set, an attribution comment and a signature comment (who
ran the command, and when) are written right after the TOC, inside the markers.
--hide-footer suppresses both.
Status messages - the backup path, or a warning about a non-local input - are printed to stderr, not stdout.
Use --skip-header to make gh-md-toc ignore everything up to and including the
end marker (<!--te-->) when building the TOC. Only the content after that marker
is scanned for headings.
$ ./gh-md-toc --skip-header README.mdThe point is to hide the topmost headlines - the document's own title, and any
other heading placed above the marker block, are excluded from the generated TOC.
Without --skip-header, a document's title heading gets picked up like any other
heading and shows up as an entry in its own TOC.
This matters when combined with --insert: place the markers right below your
title, e.g. # Project followed by <!--ts-->/<!--te-->, and add --skip-header
to keep Project from appearing as the first entry of the TOC sitting right under
it.
--skip-header has no effect on documents that don't contain an end marker; the
whole document is scanned, exactly as without the flag.
Use --start-depth=INT to control the starting header level (i.e. include only the levels
starting with INT)
➥ ./gh-md-toc --start-depth=1 ~/projects/Dockerfile.vim/README.md
Table of Contents
=================
* [Or using Pathogen:](#or-using-pathogen)
* [Or using Vundle:](#or-using-vundle)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)Use --depth=INT to control how many levels of headers to include in the TOC
➥ ./gh-md-toc --depth=1 ~/projects/Dockerfile.vim/README.md
Table of Contents
=================
* [Dockerfile\.vim](#dockerfilevim)
* [Screenshot](#screenshot)
* [Installation](#installation)
* [License](#license)➥ ./gh-md-toc ~/projects/my/Dockerfile.vim/README.md | grep Docker
* [Dockerfile\.vim](#dockerfilevim)
➥ ./gh-md-toc --no-escape ~/projects/my/Dockerfile.vim/README.md | grep Docker
* [Dockerfile.vim](#dockerfilevim)GitHub's /markdown/raw API renders at most 400 KB per request. A larger document is
split automatically at blank lines outside code blocks, converted in several requests
and reassembled into one TOC, with duplicate anchors numbered as they would be for
the whole document.
The only visible difference is the number of API calls: a 2 MB document costs six requests instead of one, which reaches the rate limit six times faster. Pass a token (see below) when you work with documents of that size.
A document is only rejected when a single line is larger than the limit, since there is no way to split it without changing what it renders to.
Without a GitHub token, the /markdown/raw endpoint allows very few requests per hour; when the rate limit is exceeded, the tool will suggest passing a token via --token, GH_TOC_TOKEN, or token.txt.
All your tokents are here.
The token is resolved in this order: the --token flag, then the GH_TOC_TOKEN
environment variable, then a token.txt file placed next to the executable. The file
is the last fallback and is only used when neither the flag nor the environment
variable is set.
Example for cli argument:
➥ ./gh-md-toc --depth=1 --token=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 README.md
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 README.md
Table of Contents
=================
* [github\-markdown\-toc](#github-markdown-toc)
* [Table of Contents](#table-of-contents)
* [Installation](#installation)
* [Tests](#tests)
* [Usage](#usage)
* [LICENSE](#license)If you're using GitHub Enterprise Server, you can override default URL for API:
➥ GH_TOC_URL=https://api.github.mycompany.com ./gh-md-toc README.mdJust 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 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/ld-linux-x86-64.so.2 as its interpreter. You can solve this by installing libc6-compat alongside downloading the Linux amd64 build.
apk add libc6-compatSee LICENSE file.