DocToc is a command-line tool that generates tables of contents for markdown files inside local git repository, with links compatible with anchors generated by GitHub or other sites.
The tool solves the problem of maintaining accurate, up-to-date tables of contents in markdown documentation. It works by scanning markdown files for headings and automatically generating a linked table of contents that can be inserted into the document. The generated TOC is wrapped in special comment markers that allow DocToc to update the table when the document changes, rather than requiring manual edits each time headings are added or modified.
DocToc suits projects with markdown-heavy documentation that need to keep tables of contents synchronized with document structure. It works on individual files or recursively through directories, processing files with .md, .markdown, and .mdx extensions while ignoring .git and node_modules directories by default. The tool offers several modes useful for different workflows: a dry-run option for CI environments to verify documentation is up to date, a stdout mode for viewing output without modifying files, and an update-only mode that leaves files without existing TOCs untouched, making it compatible with tools like lint-staged. It can be integrated as a git hook to automate TOC updates as part of the commit process, and a Docker image is available for containerized environments.
The project maintains active continuous integration testing. Development activity shows consistent engagement with bug fixes and feature improvements being merged regularly. The tool receives updates addressing user-reported issues and requests for enhanced functionality across its various configuration options and output modes.
