Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 21 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.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](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.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 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-NodeenvTable 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.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'```
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.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:
```bash
➥ 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:
```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-batsHow 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
✓ --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
```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
```