$ show thlorenz/doctoc
doctoc is a CLI tool that automatically generates and updates a table of contents (TOC) for Markdown files. It parses markdown and HTML headings, creates anchor links compatible with GitHub, GitLab, Bitbucket, and other platforms, and inserts the TOC into the file between special comment markers. The tool supports a wide range of configuration options including heading level limits, custom titles, ordered/unordered lists, indentation styles, and pragma comment styles (legacy or compact). It can operate on single files or recursively scan directories, and offers a dry-run mode for CI validation. The architecture is a straightforward Node.js CLI application. The entry point is `doctoc.js`, which parses command-line arguments via `minimist` and delegates to `lib/transform.js` for the core TOC generation logic. `lib/transform.js` uses `@textlint/markdown-to-ast` to parse Markdown into an AST, `htmlparser2` to extract HTML headings, and `anchor-markdown-header` to generate anchor links. `lib/content-generation.js` handles the creation of comment markers (pragmas) for different syntaxes (`.md`, `.mdx`) and styles. `lib/file.js` provides recursive file discovery. The tool is distributed as an npm package and can also be used as a pre-commit hook via the provided `.pre-commit-hooks.yaml`. External dependencies are minimal and well-chosen: `@textlint/markdown-to-ast` for parsing, `htmlparser2` for HTML parsing, `anchor-markdown-header` for anchor generation, `loglevel` for logging, and `minimist` for argument parsing. The codebase is written in CommonJS style with `'use strict'`, and tests use the `tap` framework with a comprehensive suite of fixtures covering edge cases like frontmatter, emoji headers, nested markdown, and various formatting options.
The LLM identified 2 files worth highlighting for reuse:
Generates comment markers (pragmas) for TOC insertion in Markdown and MDX files. Supports both legacy (verbose) and compact pragma styles. Also provides skip and exclude tags. This module is self-contained, has no internal dependencies beyond its own functions, and can be extracted and reused in any project that needs to insert or detect comment-based markers in markdown content.
Extracts HTML heading tags (h1-h6) from a markdown AST, filtering by level and position. Uses htmlparser2 to parse raw HTML blocks and associates each heading with its line number in the original document. Handles edge cases like headings inside code blocks (via pre tag detection) and multi-line headings. While coupled to the @textlint/markdown-to-ast node structure, the core logic of parsing HTML for headings is reusable in other markdown processing tools.