GitHub - ekalinin/github-markdown-toc.go: Easy TOC creation for GitHub README.md (in go) (original) (raw)

github-markdown-toc

Go Report Card codecov Go Reference MIT license GitHub release (latest by date) e2e test

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

The advantages of this implementation:

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

Installation

Precompiled binaries

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

Compiling from source

You need golang installed in your OS:

$ make build $ ./gh-md-toc --help usage: gh-md-toc [] [...]

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: [] 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 test coverage: 28.8% of statements ok _~/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

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 2015

Table of Contents

Remote files

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

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

And here is a result:

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

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

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

Created by gh-md-toc

Starting Depth

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

Created by gh-md-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.md

Table of Contents

No escape

➥ ./gh-md-toc ~/projects/my/Dockerfile.vim/README.md | grep Docker

➥ ./gh-md-toc --no-escape ~/projects/my/Dockerfile.vim/README.md | grep Docker

GitHub token

All your tokents are here.

Example for cli argument:

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

Table of Contents

Example for environment variable:

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

Table of Contents

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 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/ld-linux-x86-64.so.2 as its interpreter. You can solve this by installing libc6-compat alongside downloading the Linux amd64 build.

LICENSE

See LICENSEfile.