// the take
A small CLI and library that scans a markdown file's headings and generates a table of contents, either printed to stdout or injected in place between `<!-- toc -->`/`<!-- tocstop -->` markers. It's aimed at anyone maintaining a README or docs set who wants an auto-generated, auto-updating TOC instead of writing one by hand.
The insert mechanism is idempotent — re-running against an existing `<!-- toc -->...<!-- tocstop -->` block replaces it rather than duplicating, so it's safe to wire into a pre-commit hook or doc build step. It correctly skips headings that appear inside fenced code blocks, YAML front matter, or `#`-comment syntax in other languages, which is exactly where naive regex-based TOC generators break. It exposes the underlying pieces (`toc.json`, `slugify`, `linkify`, `bullets`) as well as a Remarkable plugin hook, so you're not stuck with the default renderer if you need custom output. Its use as a transitive/dev dependency in thousands of projects (Prettier, Mocha, webpack, Sass) means the heading-parsing edge cases have had a lot of real-world exercise.
No commits since mid-2024 and it's built on Remarkable, a markdown parser that itself isn't CommonMark/GFM-complete and isn't getting updated — so newer syntax (GFM alerts, strikethrough edge cases, footnotes) may parse headings incorrectly or not at all. The slugify logic is a basic non-word-character strip, not GitHub's actual slugger, so generated anchors can silently diverge from GitHub's rendered heading IDs on anything with punctuation, emoji, or non-ASCII text. The `-i` in-place file edit has no dry-run or diff output, so a bad run means recovering via git rather than reviewing before writing. It's effectively a single-maintainer project with no visible CI, so correctness regressions would likely sit unnoticed rather than get caught before a release.
We read the README, the directory tree and a key source file in October 2026. Nobody pays to be listed. How we judge →