github-markdown-toc is a shell script that generates tables of contents for GitHub README files and wiki pages without requiring additional software installation.
The tool solves the problem of manually creating and maintaining table of contents in markdown documentation. It works by parsing markdown headers and generating clickable links that can be inserted into a document. The tool can process input from three sources: standard input, local markdown files on the filesystem, and remote HTML files hosted on GitHub. It supports processing multiple files in a single command and can automatically insert and update tables of contents within marked sections of a file using comment delimiters.
The tool suits developers who want a lightweight, dependency-free solution for managing documentation structure. It works well for projects that need to keep README files synchronized with their actual content structure. For Windows users, the README recommends a Go-based implementation as a more reliable alternative with parallel processing capabilities and no dependencies. The tool can be integrated into GitHub Actions workflows for automated table of contents generation and updates.
The project maintains active testing infrastructure using the bats testing framework. The tool has been verified to work on Ubuntu and macOS, with Docker support available for containerized environments. GitHub token authentication is supported for handling rate-limiting issues when processing remote files. The codebase relies on standard Unix utilities including curl or wget, awk, grep, and sed, keeping the dependency footprint minimal.
