gh-md-toc

gh-md-toc — is for you if you want to generate TOC (Table Of Content) for a README.md or a GitHub wiki page without installing additional software.

It's my try to fix a problem:

• github/issues/215

gh-md-toc is able to process:

• stdin
• local files (markdown files in local file system)
• remote files (html files on github.com)

gh-md-toc tested on Ubuntu, and macOS High Sierra (gh-md-toc release 0.4.9). If you want it on Windows, you better to use a golang based implementation:

• github-markdown-toc.go

It's more solid, reliable and with ability of a parallel processing. And absolutely without dependencies.

Table of contents

• Installation
• Usage
  • STDIN
  • Local files
  • Remote files
  • Multiple files
  • Combo
  • Auto insert and update TOC
  • GitHub token
  • TOC generation with Github Actions
• Tests
• Dependency
• Docker
  • Local
  • Public

Installation

Linux (manual installation)

$ wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc
$ chmod a+x gh-md-toc

MacOS (manual installation)

$ curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
$ chmod a+x gh-md-toc

Linux or MacOS (using Basher)

$ basher install ekalinin/github-markdown-toc
# `gh-md-toc` will automatically be available in the PATH

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
Table 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.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 helpfor 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.

If you do not want to copy from console you can add > YOURFILENAME.md at the end of the command like ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md > table-of-contents.md and this will store the table of contents to a file named table-of-contents.md in your current folder.

And here is a result:

• README.md with TOC

Moreover, it's able to work with GitHub's wiki pages:

➥ ./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv
Table of Contents
=================
* [Who Uses Nodeenv?](#who-uses-nodeenv)* [OpenStack](#openstack)* [pre-commit.com](#pre-commitcom)

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)

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 https://github.com/ekalinin/github-markdown-toc -->

Auto insert and update TOC

Just put into a file these two lines:

<!--ts-->
<!--te-->

And run:

$ ./gh-md-toc --insert README.test.md
Table of Contents
=================
* [gh-md-toc](#gh-md-toc)* [Installation](#installation)* [Usage](#usage)* [STDIN](#stdin)* [Local files](#local-files)* [Remote files](#remote-files)* [Multiple files](#multiple-files)* [Combo](#combo)* [Tests](#tests)* [Dependency](#dependency)!! TOC was added into: 'README.test.md'!! Origin version of the file: 'README.test.md.orig.2018-02-04_192655'!! TOC added into a separate file: 'README.test.md.toc.2018-02-04_192655'<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

Now check the same file:

➜ grep -A15 "<\!\-\-ts" README.test.md
<!--ts-->* [gh-md-toc](#gh-md-toc)* [Table of contents](#table-of-contents)* [Installation](#installation)* [Usage](#usage)* [STDIN](#stdin)* [Local files](#local-files)* [Remote files](#remote-files)* [Multiple files](#multiple-files)* [Combo](#combo)* [Auto insert and update TOC](#auto-insert-and-update-toc)* [Tests](#tests)* [Dependency](#dependency)<!-- Added by: <your-user>, at: 2018-02-04T19:38+03:00 --><!--te-->

Next time when your file will be changed just repeat the command (./gh-md-toc --insert ...) and TOC will be refreshed again.

GitHub token

All your tokens are here.

You will need them if you get an error like this:

Parsing local markdown file requires access to github API
Error: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limiting
or place github auth token here: ./token.txt

A token can be used as an env variable:

➥ GH_TOC_TOKEN=2a2dab...563 ./gh-md-toc 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)

Or from a file:

➥ echo"2a2dab...563"> ./token.txt
➥ ./gh-md-toc 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)

TOC generation with Github Actions

Config:

on:
push:
branches: [main]paths: ['foo.md']jobs:
build:
runs-on: ubuntu-latesttimeout-minutes: 5steps:
- uses: actions/checkout@v2
- run: | curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc chmod a+x gh-md-toc ./gh-md-toc --insert --no-backup --hide-footer foo.md rm gh-md-toc - uses: stefanzweifel/git-auto-commit-action@v4with:
commit_message: Auto update markdown TOC

Tests

Done with bats. Useful articles:

• https://www.engineyard.com/blog/how-to-use-bats-to-test-your-command-line-tools/
• http://blog.spike.cx/post/60548255435/testing-bash-scripts-with-bats

How to run tests:

➥ make test ✓ TOC forlocal README.md
✓ TOC for remote README.md
✓ TOC for mixed README.md (remote/local)
✓ TOC for markdown from stdin
✓ --help
✓ --version
6 tests, 0 failures

Dependency

• curl or wget
• awk (mawk is not tested)
• grep
• sed
• bats (for unit tests)

Tested on Ubuntu 14.04/14.10 in bash/zsh.

Docker

Local

• Build

$ docker build -t markdown-toc-generator .

• Run on an URL

$ docker run -it markdown-toc-generator https://github.com/ekalinin/envirius/blob/master/README.md

• Run on a local file (need to share volume with docker)

$ docker run -it -v /data/ekalinin/envirius:/data markdown-toc-generator /data/README.md

Public

$ docker pull evkalinin/gh-md-toc:0.7.0
$ docker images | grep toc
evkalinin/gh-md-toc 0.7.0 0b8db6aed298 11 minutes ago 147MB
$ docker run -it evkalinin/gh-md-toc:0.7.0 \
https://github.com/ekalinin/envirius/blob/master/README.md