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
1.1.0
You need golang 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
--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 golang 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.003s
Here'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.004s
You 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)
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)
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.md
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 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-compat
See LICENSE file.