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/1.1.0/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$ 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.
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)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.
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.