# jonschlinkert/markdown-toc

API and CLI for generating a markdown TOC (table of contents) for a README or any markdown files. Uses Remarkable to parse markdown. Used by NASA/openmct, Prisma, Joi, Mocha, Sass, Prettier, Orbit DB, FormatJS, Raneto, hapijs/code, webpack-flow, docusaurus, release-it, ts-loader, json-server, reactfire, bunyan, husky, react-easy-state, react-snap, chakra-ui, carbon, alfresco, repolinter, Assemble, Verb, and thousands of other projects.

Repository: https://github.com/jonschlinkert/markdown-toc
Canonical: https://ross.abutalabs.com/products/markdown-toc
Homepage: https://github.com/jonschlinkert
Language: JavaScript
License: MIT
License Family: permissive
Topics: toc-generator, table-of-contents, toc, markdown, navigation, project, readme, md, markdown-toc, node, nodejs, javascript, jonschlinkert, remarkable
Last push: 2024-08-09T14:53:13+00:00

## Health v2 (maintenance only)
Score: 32/100 (v2, computed 2026-09-03T02:20:16.233290+00:00)
- activity 0, release rhythm 35, longevity 100
- inputs: {"age_days": 4681, "days_push": 754, "days_rel": null, "gap_med": null, "n_releases_24m": 0}
- flags: no_releases
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1756, forks 712 (observed 2026-08-28T04:05:32.153417+00:00)

## What it is
A Node.js library and CLI that generates a table of contents for markdown files like READMEs, using Remarkable to parse headings. It can inject the TOC directly into a file at a <!-- toc --> marker and also exposes a JSON API.

## Use cases
- generate a table of contents for a README
- auto-insert TOC into markdown docs
- extract heading structure from a markdown file as JSON
- add navigation links to documentation
- keep README TOC in sync with headings via a script

## When to choose
- you maintain markdown docs or READMEs and want an auto-generated, linkable TOC
- you need a programmatic API to extract markdown heading structure
- you want a simple CLI to inject a TOC at a marker in place

## When to avoid
- you need a full static site generator or docs framework
- your project uses MDX or non-standard markdown syntax Remarkable may not handle
- you need actively developed features rather than a stable maintenance-mode tool

## Facets
- artifact type: library
- maturity: maintenance
- function: markdown, parser, cli, documentation, developer-tools
- domain: documentation, developer-tools
- platform: cli, cross-platform
- tags: table-of-contents, toc-generator, remarkable, readme, npm-package, command-line, nodejs

## Member repositories
- jonschlinkert/markdown-toc (main) score 32

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:05:32.153417+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T03:27:52.265875+00:00, confidence not recorded.
  - readme: https://github.com/jonschlinkert/markdown-toc (fetched 2026-08-28T04:05:32.153417+00:00, sha 99a410d61afa)
  - homepage: https://github.com/jonschlinkert (fetched 2026-08-29T11:06:14.029976+00:00, sha 5ff17830cf36)
  - registry_npm: https://registry.npmjs.org/markdown-toc (fetched 2026-08-29T11:06:14.038954+00:00, sha 0dfa2f0b2ce8)
- Data as of 2026-08-30T08:39:29.467469+00:00.