github-markdown-toc

This is a golang based implementation of thegithub-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 isconnected to the Internet.

Table of Contents

• github-markdown-toc
• Installation
  • Precompiled binaries
  • Compiling from source
  • Go Install
  • Homebew (Mac only)
• Tests
• Usage
  • STDIN
  • Local files
  • Remote files
  • Multiple files
  • Combo
  • Starting Depth
  • Depth
  • No Escape
  • Github token
  • GitHub Enterprise Server
  • Bash/ZSH auto-complete
• Alpine Linux
• LICENSE

Created bygh-md-toc

Installation

Precompiled binaries

See the releases page, "Downloads" section:

• https://github.com/ekalinin/github-markdown-toc.go/releases

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.tgzgh-md-toc$ ./gh-md-toc --version1.1.0

Compiling from source

You need golang installed in your OS:

$ make build$ ./gh-md-toc --helpusage: 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.

Go Install

You need golang installed in your OS:

go install "github.com/ekalinin/github-markdown-toc.go/cmd/gh-md-toc@latest"

Homebew (Mac only)

$ brew install github-markdown-toc

Tests

$ make testcoverage: 28.8% of statementsok      _~/projects/my/github-toc.go    0.003s

Usage

STDIN

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)

Local files

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 2015Table 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 README.md like this:

• README.md without TOC

And you want to generate TOC for it.

There is nothing easier:

➥ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.mdTable 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 originalREADME.md.

And here is a result:

• README.md with TOC

Multiple files

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.0You 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.200suser    0m0.040ssys     0m0.004s

➥ time (./gh-md-toc README.md ../envirius/README.ru.md ../github-toc/README.md > /dev/null)real    0m0.784suser    0m0.036ssys     0m0.004s

Combo

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)

Starting Depth

Use--start-depth=INT to control the starting header level (i.e. include only the levelsstarting withINT)

➥ ./gh-md-toc --start-depth=1 ~/projects/Dockerfile.vim/README.mdTable 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)

Depth

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

➥ ./gh-md-toc --depth=1 ~/projects/Dockerfile.vim/README.mdTable of Contents=================  * [Dockerfile\.vim](#dockerfilevim)  * [Screenshot](#screenshot)  * [Installation](#installation)  * [License](#license)

No escape

➥ ./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 token

All your tokents arehere.

Example for cli argument:

➥ ./gh-md-toc --depth=1 --token=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 README.mdTable 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.mdTable of Contents=================* [github\-markdown\-toc](#github-markdown-toc)* [Table of Contents](#table-of-contents)* [Installation](#installation)* [Tests](#tests)* [Usage](#usage)* [LICENSE](#license)

GitHub Enterprise Server

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

Bash/ZSH auto-complete

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

# for zsheval "$(gh-md-toc --completion-script-zsh)"# for basheval "$(gh-md-toc --completion-script-bash)"

Alpine Linux

Alpine Linux usesmusl instead ofglibc by default. If you installbinutils 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 itsinterpreter. You can solve this by installinglibc6-compat alongside downloading the Linuxamd64 build.

apk add libc6-compat

LICENSE

SeeLICENSEfile.

Constants¶

Variables¶

Functions¶

Types¶

type GHDoc struct {PathstringAbsPathsboolStartDepthintDepthintEscapeboolGhTokenstringIndentintDebugbool// contains filtered or unexported fields}

func NewGHDoc(Pathstring, AbsPathsbool, StartDepthint, Depthint, Escapebool, Tokenstring, Indentint, Debugbool) *GHDoc

func (doc *GHDoc) Convert2HTML()error

func (doc *GHDoc) GetToc() *GHToc

func (doc *GHDoc) GrabToc() *GHToc

func (doc *GHDoc) IsRemoteFile()bool

func (doc *GHDoc) SetGHURL(urlstring) *GHDoc

func (doc *GHDoc) SetReVersion(vstring) *GHDoc

type GHToc []string

func (toc *GHToc) Print(wio.Writer)error