github-markdown-toc
Tool for generating Table of Contents for Markdown files
GraphCanon updated 2w · GitHub synced 2w
Decision brief
github-markdown-toc is a shell-based tool to create table of contents for Markdown files on GitHub without requiring additional software installation.
Good fit when
- For users looking to generate a TOC from local or remote Markdown files, including README.md and wiki pages, in environments where installing software is either not allowed or unnecessary.
- If you are working with Ubuntu or macOS and want to avoid dependencies that some other solutions might require.
Avoid when
- In Windows environments since it relies on shell scripting, although a Go-based alternative exists for more reliable cross-platform use.
- For projects requiring advanced features such as parallel processing, which are supported by competitors written in languages better suited for these tasks.
Observed Jul 14, 2026 · Source: enrich:decision_facts
Verify the decision
Maintenance and security
Full trust report- Maintenance
- Dormant (657d since push)
- As of 2w
- Provenance
- Not a fork · Personal account
- As of 2w
- Security (OSV)
- No lockfile
- As of 1mo
Public GitHub metadata and optional OSV scans. Signals, not a guarantee. Trust methodology.
Install
git clone https://github.com/ekalinin/github-markdown-tocSimilar tools
Same-category neighbours. No typed graph edges are catalogued for this tool yet.
Evidence and technical details
Sourced facts, taxonomy, compatibility claims, README excerpt, and machine-readable endpoints.
Overview
Provides functionality to generate table of contents for README.md and GitHub wiki pages without installing additional software.
Capability facts
- Deploy
- Self-host
Source: dockerfile:Dockerfile · Aug 1, 2026
- Docker
- Dockerfile present
Source: dockerfile:Dockerfile · Aug 1, 2026
- Languages
- shell
Source: github.language · Aug 1, 2026
Categories
Tags
README
gh-md-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:
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:
It's more solid, reliable and with ability of a parallel processing. And absolutely without dependencies.
Table of contents
- Installation
- Usage
- STDIN
- Local files
- Remote files
- Multiple files
- Combo
- Auto insert and update TOC
- GitHub token
- TOC generation with Github Actions
- 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:
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
For agents
This page has a .md twin and JSON over the API.