gh-md-toc

gh-md-toc — is for you if you want to generate TOC for README.md or GitHub's wiki page and don't want to install any additional software.

It's my try to fix a problem:

• github/issues/215

gh-md-toc is able to proccess:

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

gh-md-toc tested on Ubuntu only. If you want it on Mac OS X or 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

• gh-md-toc
• Table of contents
• Installation
• Usage
  • STDIN
  • Local files
  • Remote files
  • Multiple files
  • Combo
• Tests
• Dependency

Installation

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

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 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)

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.

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 [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

Tests

Done with bats. Useful articles:

• https://blog.engineyard.com/2014/bats-test-command-line-tools
• http://blog.spike.cx/post/60548255435/testing-bash-scripts-with-bats

How to run tests:

➥ make test Пн. марта 23 13:59:27 MSK 2015
✓ 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
• grep
• sed
• bats (for unit tests)

Tested on Ubuntu 14.04/14.10 in bash/zsh.