DocToc
Generates and updates table of contents for markdown files in local git repositories with GitHub-compatible anchors.
What is DocToc?
DocToc is a command-line tool that automatically generates and maintains a table of contents for Markdown files within a local Git repository. It scans directories recursively to create TOCs, ensuring links are compatible with anchor formats used by platforms like GitHub, GitLab, and Bitbucket. This automates documentation maintenance and improves navigation for readers.
Technical writers, open-source maintainers, and developers who manage documentation in Markdown files within Git repositories and want to automate TOC creation and updates.
Developers choose DocToc for its lightweight, non-intrusive automation with fine-grained control over TOC placement, formatting, and platform-specific link compatibility. It stands out by offering incremental updates without duplicates, CI/CD integration with dry-run mode, and flexible configuration options like custom headers, footers, and heading level ranges.
Overview
📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.
Use Cases
Best For
- Automatically generating and updating table of contents for all Markdown files in a Git repository with a single command.
- Ensuring TOC links are compatible with specific platforms like GitHub, GitLab, Bitbucket, Node.js, or Ghost via command-line flags.
- Integrating TOC maintenance into CI/CD pipelines using dry-run mode to check if documentation is up-to-date during builds.
- Using as a pre-commit Git hook to automatically update TOCs before commits, keeping documentation synchronized.
- Placing TOCs at custom locations within Markdown files using pragma comments, not just at the top.
- Selectively updating only files with existing TOCs or ignoring specific files to streamline documentation workflows.
Not Ideal For
- Projects using non-Markdown documentation formats like HTML or reStructuredText
- Teams that prefer graphical user interfaces over command-line tools for documentation editing
- Environments where installing Node.js is prohibited or impractical
Pros & Cons
Pros
Scans directories recursively to create and update table of contents for all Markdown files with a single command, as demonstrated in the 'Adding toc to all files in a directory' section.
Supports link formats for GitHub, GitLab, Bitbucket, Node.js, and Ghost via command-line flags, ensuring TOCs work seamlessly across different platforms.
Intelligently updates existing TOCs without creating duplicates when re-run, as highlighted in the 'Update existing doctoc TOCs effortlessly' section.
Offers dry-run mode for checking if docs are up-to-date in build pipelines and pre-commit Git hook support, facilitating automated documentation maintenance.
Cons
The --minlevel option only supports values 1 and 2, restricting flexibility for documents with complex heading hierarchies, as noted in the configuration section.
Requires Node.js and npm for installation, which adds overhead in environments without JavaScript tooling or where minimal dependencies are preferred.
Lacks a graphical interface, making it less accessible for non-technical users or those who prefer visual tools for documentation workflows.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.