ekalinin/github-markdown-tocPublic

NotificationsYou must be signed in to change notification settings
Fork2.7k
Star3.3k

Easy TOC creation for GitHub README.md

License

MIT license

3.3k stars 2.7k forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 241 Commits
.github		.github
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
gh-md-toc		gh-md-toc

Repository files navigation

gh-md-toc

gh-md-toc — is for you if youwant to generate TOC (Table Of Content) for a README.md ora GitHub wiki pagewithout 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, youbetter to use a golang based implementation:

github-markdown-toc.go

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

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

$ 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.mdTable 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 versionsfor each plugin](#check-available-versions-for-each-plugin)* [Create an environment](#create-an-environment)* [Activate/deactivate environment](#activatedeactivate-environment)* [Activatingin a new shell](#activating-in-a-new-shell)* [Activatingin 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 somethingin environment without enabling it](#do-something-in-environment-without-enabling-it)* [Get help](#get-help)* [Gethelpfor 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)* [READMEin another language](#readme-in-another-language)

That's all! Now all you need — is copy/paste result from console into originalREADME.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-NodeenvTable 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.mdTable 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 arehere.

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

Parsing local markdown file requires access to github APIError: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limitingor 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.mdTable 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.mdTable 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 withbats.Useful articles:

How to run tests:

➥ maketest                                                                                                                  ✓ TOCforlocal README.md ✓ TOCfor remote README.md ✓ TOCfor mixed README.md (remote/local) ✓ TOCfor markdown from stdin ✓ --help ✓ --version6 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 tocevkalinin/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