Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ekalinin/github-markdown-toc

Easy TOC creation for GitHub README.md
https://github.com/ekalinin/github-markdown-toc
github markdown shell table-of-contents toc
Last synced: 25 days ago
JSON representation
Easy TOC creation for GitHub README.md
Host: GitHub
URL: https://github.com/ekalinin/github-markdown-toc
Owner: ekalinin
License: mit
Created: 2014-09-02T15:33:16.000Z (about 10 years ago)
Default Branch: master
Last Pushed: 2024-08-04T15:25:09.000Z (3 months ago)
Last Synced: 2024-10-01T17:41:21.856Z (about 1 month ago)
Topics: github, markdown, shell, table-of-contents, toc
Language: Shell
Homepage:
Size: 165 KB
Stars: 3,221
Watchers: 40
Forks: 2,749
Open Issues: 25
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

favorite-link - 为 GitHub README.md 轻松创建 TOC。
awesome-trilium - https://github.com/ekalinin/github-markdown-toc
awesome-starts - ekalinin/github-markdown-toc - Easy TOC creation for GitHub README.md (shell)
awesome-robotics-ai-companies - Easy TOC for Github README
jimsghstars - ekalinin/github-markdown-toc - Easy TOC creation for GitHub README.md (Shell)
README

        gh-md-toc

=========

[![CI](https://github.com/ekalinin/github-markdown-toc/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ekalinin/github-markdown-toc/actions/workflows/ci.yml)

![GitHub release (latest by date)](https://img.shields.io/github/v/release/ekalinin/github-markdown-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](https://github.com/isaacs/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](https://github.com/ekalinin/github-markdown-toc.go)

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

absolutely without dependencies.

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)

      * [GitHub token](#github-token)

      * [TOC generation with Github Actions](#toc-generation-with-github-actions)

   * [Tests](#tests)

   * [Dependency](#dependency)

   * [Docker](#docker)

     * [Local](#local)

     * [Public](#public)

Installation

============

Linux (manual installation)

```bash

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

$ chmod a+x gh-md-toc

```

MacOS (manual installation)

```bash

$ 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](https://github.com/basherpm/basher))

```bash

$ 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:

```bash

➥ 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:

```bash

➥ ./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](https://github.com/ekalinin/envirius/blob/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.md)

And you want to generate TOC for it.

There is nothing easier:

```bash

➥ ./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](https://github.com/ekalinin/envirius/blob/24ea3be0d3cc03f4235fa4879bb33dc122d0ae29/README.md)

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

```bash

➥ ./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:

```bash

➥ ./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:

```bash

➥ ./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)

```

Auto insert and update TOC

--------------------------

Just put into a file these two lines:

```

```

And run:

```bash

$ ./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'

```

Now check the same file:

```bash

➜ grep -A15 "<\!\-\-ts" README.test.md

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

```

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](https://github.com/settings/tokens).

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:

```bash

➥ 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:

```bash

➥ 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:

```yaml

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/0.8.0/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](https://github.com/bats-core/bats-core).

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:

```bash

➥ 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

```shell

$ docker build -t markdown-toc-generator .

```

* Run on an URL

```shell

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

```shell

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

```

Public

-------

```shell

$ 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

```