github-markdown-toc

Easy TOC creation for GitHub README.md

3,243

2,752

3,243

View on GitHub

Top Related Projects

doctoc

4,266

📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.

Quick Overview

GitHub-markdown-toc is a command-line tool that automatically generates a table of contents for Markdown files. It's particularly useful for creating and maintaining table of contents for GitHub README files and other Markdown documents. The tool can process local files or remote GitHub repositories.

Pros

Easy to use with a simple command-line interface
Supports both local and remote Markdown files
Generates clickable links in the table of contents
Can be integrated into CI/CD pipelines for automatic README updates

Cons

Limited to Markdown files only
May require manual adjustments for complex document structures
Doesn't support automatic updating of existing table of contents
Requires shell access, which may not be available in all environments

Code Examples

Generate a table of contents for a local file:

gh-md-toc README.md

Generate a table of contents for a remote GitHub repository:

gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md

Insert a table of contents into a file:

gh-md-toc --insert README.md

Getting Started

To get started with github-markdown-toc, follow these steps:

Install the tool:

curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
chmod a+x gh-md-toc
sudo mv gh-md-toc /usr/local/bin/

Generate a table of contents for your README:
```
gh-md-toc README.md
```
Copy the generated table of contents and paste it into your README file.

For more advanced usage, refer to the project's documentation on GitHub.

Competitor Comparisons

doctoc

4,266

📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.

Pros of doctoc

Supports multiple markup languages (Markdown, reStructuredText, AsciiDoc)
Can update existing TOCs in-place
Offers a CLI tool for easy integration into workflows

Cons of doctoc

Requires Node.js to be installed
May struggle with complex document structures
Limited customization options for TOC formatting

Code Comparison

doctoc:

var transform = require('./transform');
var file = require('./file');

module.exports = function updateToc(content, mode, maxHeaderLevel, title) {
  return transform(content, mode, maxHeaderLevel, title);
};

github-markdown-toc:

#!/usr/bin/env bash

gh_toc_version="0.8.0"

gh_user_agent="gh-md-toc v$gh_toc_version"

#
# Download rendered file
#

Summary

Both doctoc and github-markdown-toc are useful tools for generating tables of contents for Markdown files. doctoc offers broader language support and in-place updating, but requires Node.js. github-markdown-toc is a simpler bash script with fewer dependencies. The choice between them depends on your specific needs and environment.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

gh-md-toc

GitHub release (latest by date)

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.

Installation
Usage
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 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 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-latest
    timeout-minutes: 5
    steps:
      - 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@v4
        with:
          commit_message: Auto update markdown TOC

Tests

Done with bats. Useful articles:

How to run tests:

â¥ make test                                                                                                                 

 â TOC for local 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

Top Related Projects

doctoc

4,266

📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot