@0dep/toc 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## v0.0.1 - 2026-09-12
+
+- initial release: `buildToc`, `updateToc`, `slugify`, `headingText`, and the `toc` bin

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Zerodep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,392 @@
+# @0dep/toc
+
+[![Build](https://github.com/zerodep/toc/actions/workflows/build.yaml/badge.svg)](https://github.com/zerodep/toc/actions/workflows/build.yaml)[![Build (Windows)](https://github.com/zerodep/toc/actions/workflows/build-windows.yaml/badge.svg)](https://github.com/zerodep/toc/actions/workflows/build-windows.yaml)[![Coverage Status](https://coveralls.io/repos/github/zerodep/toc/badge.svg?branch=main)](https://coveralls.io/github/zerodep/toc?branch=main)
+
+Generate a GitHub flavoured table of contents for markdown files. No dependencies, ESM and CommonJS. The library is string in, string out and runs in the browser too, the `toc` bin needs Node 20 or later.
+
+The toc is written between `<!-- toc -->` and `<!-- /toc -->` markers, and only there. Nothing outside the markers is ever touched, nothing is inserted or guessed. Slugs match GitHub's anchors.
+
+<!-- toc -->
+
+- [Install](#install)
+- [Markers](#markers)
+  - [Several tocs in one document](#several-tocs-in-one-document)
+  - [Options](#options)
+  - [What is left alone](#what-is-left-alone)
+- [CLI](#cli)
+  - [Options](#options-1)
+  - [Output and exit code](#output-and-exit-code)
+  - [Dry run](#dry-run)
+  - [Keep the toc fresh with npm test](#keep-the-toc-fresh-with-npm-test)
+  - [With prettier](#with-prettier)
+- [API](#api)
+  - [`buildToc(source)`](#buildtocsource)
+  - [`renderToc(source[, fromLine[, options]])`](#rendertocsource-fromline-options)
+  - [`findMarkers(source)`](#findmarkerssource)
+  - [`slugify(text)`](#slugifytext)
+  - [`headingText(markdown)`](#headingtextmarkdown)
+  - [`TOC_START` and `TOC_END`](#toc_start-and-toc_end)
+- [Headings](#headings)
+  - [What is listed](#what-is-listed)
+  - [Labels](#labels)
+  - [Slugs](#slugs)
+- [License](#license)
+
+<!-- /toc -->
+
+## Install
+
+```sh
+npm install --save-dev @0dep/toc
+```
+
+## Markers
+
+Put the pair where the toc should go, on their own lines. Every heading below the start marker is listed, nothing above it is, so the document title stays out of the toc when the markers sit under it.
+
+```markdown
+# My project
+
+<!-- toc -->
+<!-- /toc -->
+
+## Install
+
+## Usage
+```
+
+becomes
+
+```markdown
+# My project
+
+<!-- toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+
+<!-- /toc -->
+
+## Install
+
+## Usage
+```
+
+Running it again replaces whatever is between the markers with a fresh list, so the toc can be regenerated any number of times. A file with CRLF line endings keeps them, the toc is written with the same line ending as the rest of the file.
+
+### Several tocs in one document
+
+A document can have any number of marker pairs, for example a full toc at the top and one per section. Each pair lists every heading below its own start marker, and a later pair never shortens an earlier toc.
+
+```markdown
+# My project
+
+<!-- toc -->
+<!-- /toc -->
+
+## API
+
+<!-- toc -->
+<!-- /toc -->
+
+### get
+
+### set
+
+## License
+```
+
+The top toc lists API, get, set and License. The toc under API lists get, set and License.
+
+### Options
+
+GitHub and most other renderers support the html details element in markdown. Ask for it on the start marker and the list is wrapped in one. `collapsible` starts open and can be folded away, `collapsed` starts folded until the reader clicks the summary. This README has a `collapsed` one under [API](#api) and a `collapsible` one under [Headings](#headings).
+
+```markdown
+<!-- toc collapsed -->
+<!-- /toc -->
+```
+
+becomes
+
+```markdown
+<!-- toc collapsed -->
+<details>
+<summary>Table of contents</summary>
+
+- [Install](#install)
+- [Usage](#usage)
+
+</details>
+<!-- /toc -->
+```
+
+Both take a summary text, `<!-- toc collapsible="Contents" -->` or `<!-- toc collapsed="Contents" -->`. Any other `name="value"` pair on the start marker is put on the summary element, in the order written:
+
+```markdown
+<!-- toc collapsed="Contents" class="toc" style="font-weight: bold" -->
+<details>
+<summary class="toc" style="font-weight: bold">Contents</summary>
+
+- [Install](#install)
+
+</details>
+<!-- /toc -->
+```
+
+Renderers sanitise html, GitHub for one drops `style`, so check what yours keeps. The start marker itself is kept exactly as written, and spacing inside the comment does not matter.
+
+Anything on the start marker that is not one of the two options or a well-formed attribute makes the pair skip with a warning rather than guess: a bare name other than the two options, so a typo like `collapsable` is caught, an unquoted value like `collapsed=yes`, both options at once, or attributes without an option to give them a summary element.
+
+### What is left alone
+
+- A file without markers
+- A start marker without an end marker after it
+- An end marker with no open start marker before it
+- A pair with no headings below its start marker, since a toc that lists nothing is more likely a misplaced marker than an empty document
+- A pair whose start marker has a problem: an unknown option, both `collapsible` and `collapsed`, or attributes without either
+- Markers indented four spaces or more, that is an indented code block
+- Markers and headings inside fenced code blocks, so this README can show marker examples. A marker in inline code or in the middle of a sentence is not a marker either, only a line holding nothing but the comment
+
+A start marker pairs with the first end marker after it, a second start marker inside an open pair is treated as content and replaced with the rest of the block. The CLI reports every skipped file and pair with a warning, see below.
+
+This README has two headings named Options, the one above and the one under CLI. The second one is linked as `#options-1`, the way GitHub numbers duplicate anchors.
+
+## CLI
+
+```sh
+npx toc                        # updates README.md in the current directory
+npx toc docs/a.md docs/b.md    # several files
+npx toc docs/a.md,docs/b.md    # comma separated works too
+npx toc --dry-run README.md    # print the toc, write nothing
+npx toc --help
+```
+
+Paths are resolved against the current directory.
+
+### Options
+
+| Option          | Effect                                                                        |
+| --------------- | ----------------------------------------------------------------------------- |
+| `-n, --dry-run` | Print the toc of every pair to stdout and the status to stderr, write nothing |
+| `-h, --help`    | Show usage                                                                    |
+
+### Output and exit code
+
+One status line per file on stdout, and one warning per skipped file or pair on stderr with the marker's line number so it can be opened from a terminal.
+
+| Message                                                                           | Stream | Meaning                                              |
+| --------------------------------------------------------------------------------- | ------ | ---------------------------------------------------- |
+| `README.md: wrote TOC.`                                                           | stdout | At least one pair changed and the file was written   |
+| `README.md: TOC already up to date.`                                              | stdout | Every updatable pair was already correct             |
+| `README.md: no TOC markers, skipped.`                                             | stderr | The file has no markers                              |
+| `README.md:3: TOC start marker without end marker, skipped.`                      | stderr | Unbalanced pair                                      |
+| `README.md:3: TOC end marker without start marker, skipped.`                      | stderr | Unbalanced pair                                      |
+| `README.md:3: no headings below TOC start marker, skipped.`                       | stderr | Nothing to list for that pair                        |
+| `README.md:3: unknown TOC option foo, skipped.`                                   | stderr | The start marker has something that is not an option |
+| `README.md:3: TOC options collapsible and collapsed exclude each other, skipped.` | stderr | Pick one                                             |
+| `README.md:3: TOC attributes style need collapsible or collapsed, skipped.`       | stderr | There is no summary element to put them on           |
+| `README.md: ENOENT: no such file or directory, ...`                               | stderr | The file could not be read or written                |
+
+The exit code is 1 when a file could not be read or written or when an option is not recognised, otherwise 0. Skipped files and pairs do not affect the exit code.
+
+### Dry run
+
+With `--dry-run` nothing is written. The rendered block of every start marker goes to stdout so it can be piped or redirected, and the status line and warnings go to stderr. A start marker that would be skipped, unbalanced or with a problem, still gets its block printed, plain when its options are broken, next to the warning. A file without markers gets a block with every heading, so the output can be pasted into the document as a starting point.
+
+```sh
+npx toc --dry-run docs/new.md > toc.md
+```
+
+```text
+docs/new.md: no TOC markers, skipped.
+```
+
+### Keep the toc fresh with npm test
+
+A typical setup regenerates the toc before the tests run and lints afterwards, this README is maintained that way:
+
+```json
+{
+  "scripts": {
+    "pretest": "toc README.md",
+    "test": "mocha",
+    "posttest": "prettier . --check"
+  }
+}
+```
+
+### With prettier
+
+The generated block is written the way prettier formats markdown, so the two do not fight: `-` bullets, two spaces per nesting level, a blank line before and after the list, and html on lines of its own. Running `prettier --write` over a generated toc changes nothing, and running `toc` over a prettier formatted toc changes nothing either. This README passes both.
+
+Run `toc` before `prettier --check`, as in the scripts above, so a stale toc is regenerated rather than reported as a formatting error. The order does not matter for the content: prettier leaves headings as written, setext underlines and closing hashes included, and it never breaks a line inside a link, so toc entries survive even `proseWrap: "always"`.
+
+To regenerate the toc and format the rest of the file in one go, let a `posttoc` script run prettier with `--write` after `toc`. Prettier rewrites the prose and leaves the generated block as it is, so a second `toc` run reports the file up to date:
+
+```json
+{
+  "scripts": {
+    "toc": "toc README.md",
+    "posttoc": "prettier --write README.md"
+  }
+}
+```
+
+## API
+
+<!-- toc collapsed="Jump to" -->
+<details>
+<summary>Jump to</summary>
+
+- [`buildToc(source)`](#buildtocsource)
+- [`renderToc(source[, fromLine[, options]])`](#rendertocsource-fromline-options)
+- [`findMarkers(source)`](#findmarkerssource)
+- [`slugify(text)`](#slugifytext)
+- [`headingText(markdown)`](#headingtextmarkdown)
+- [`TOC_START` and `TOC_END`](#toc_start-and-toc_end)
+- [Headings](#headings)
+  - [What is listed](#what-is-listed)
+  - [Labels](#labels)
+  - [Slugs](#slugs)
+- [License](#license)
+
+</details>
+<!-- /toc -->
+
+```javascript
+import { buildToc, renderToc, findMarkers, slugify, headingText, TOC_START, TOC_END } from '@0dep/toc';
+```
+
+CommonJS works the same way with `require('@0dep/toc')`.
+
+### `buildToc(source)`
+
+Returns the markdown `source` with the toc between every marker pair regenerated. A pair that is unbalanced, has a problem on its start marker, or has no headings below it is left alone, and the source is returned unchanged when nothing is updated. The start marker line is kept as written.
+
+```javascript
+import { buildToc } from '@0dep/toc';
+
+const md = buildToc('# Title\n\n<!-- toc -->\n<!-- /toc -->\n\n## Install\n\n## Usage `api`\n');
+console.log(md);
+```
+
+```text
+# Title
+
+<!-- toc -->
+
+- [Install](#install)
+- [Usage `api`](#usage-api)
+
+<!-- /toc -->
+
+## Install
+
+## Usage `api`
+```
+
+### `renderToc(source[, fromLine[, options]])`
+
+Returns the toc block, markers included, for the headings below the zero based line `fromLine`, typically a start marker's line. By default every heading is listed. Returns an empty string when there is nothing to list. `options` are rendered into the start marker and the block, `{ collapsible: true }`, `{ collapsed: 'Contents', attributes: { class: 'toc' } }` and so on.
+
+```javascript
+import { renderToc } from '@0dep/toc';
+
+console.log(renderToc('# Title\n\n## Install\n\n### From npm\n'));
+```
+
+```text
+<!-- toc -->
+
+- [Title](#title)
+  - [Install](#install)
+    - [From npm](#from-npm)
+
+<!-- /toc -->
+```
+
+### `findMarkers(source)`
+
+Returns every marker pair in document order as `{ start, end, options }`, zero based line numbers outside fenced code blocks and the recognised options written on the start marker. A start marker pairs with the first end marker after it. A missing side is `-1`, a start marker without an end marker or an end marker with no open start before it. `options.attributes` holds the other `name="value"` pairs, when there are any. When the start marker cannot be used, `problem` says why and is otherwise absent.
+
+```javascript
+import { findMarkers } from '@0dep/toc';
+
+console.log(findMarkers('# Title\n\n<!-- toc collapsed -->\n<!-- /toc -->\n\n## A\n\n<!-- toc foo -->\n'));
+```
+
+```text
+[
+  { start: 2, end: 3, options: { collapsed: true } },
+  { start: 7, end: -1, options: {}, problem: 'unknown TOC option foo' }
+]
+```
+
+### `slugify(text)`
+
+The github-slugger algorithm: lowercase, drop everything that is not a letter, number, mark, space, hyphen or underscore, then turn spaces into hyphens. Nothing is trimmed or collapsed. Duplicate slugs in one toc get `-1`, `-2` and so on, like GitHub.
+
+```javascript
+import { slugify } from '@0dep/toc';
+
+console.log(slugify('Usage `api`'), slugify('Ändra värde 2 gånger'));
+```
+
+```text
+usage-api ändra-värde-2-gånger
+```
+
+### `headingText(markdown)`
+
+Reduces a heading's inline markdown to the text GitHub renders and slugs: links and images become their text, emphasis, strikethrough and html tags are removed, autolinks become their url, code span content is kept without the backticks and backslash escapes are resolved.
+
+```javascript
+import { headingText } from '@0dep/toc';
+
+console.log(headingText('Use `foo()` with [**bold**](https://example.com) \\*text\\*'));
+```
+
+```text
+Use foo() with bold *text*
+```
+
+### `TOC_START` and `TOC_END`
+
+The marker strings, `<!-- toc -->` and `<!-- /toc -->`, for code that wants to look for or insert them.
+
+## Headings
+
+<!-- toc collapsible="In this section and below" -->
+<details open>
+<summary>In this section and below</summary>
+
+- [What is listed](#what-is-listed)
+- [Labels](#labels)
+- [Slugs](#slugs)
+- [License](#license)
+
+</details>
+<!-- /toc -->
+
+### What is listed
+
+- ATX headings, `## Heading`, with up to three leading spaces and a space after the hashes, and setext headings underlined with `===` or `---`
+- Every level, 1 through 6, below the start marker. Nesting is relative to the shallowest level listed so far, so a toc under a level 2 heading that lists level 3 headings starts flush left, and the level 2 headings that follow join them at the top level
+- Not headings inside fenced code blocks, backtick or tilde
+- Not a `---` line under a list item, a table row or a blank line, which is a thematic break and not a setext heading
+
+### Labels
+
+The link text is the heading's own markdown, so inline code and emphasis are kept, with two changes:
+
+- Links and images become their text and autolinks their url, since a link cannot nest inside the toc link
+- Optional closing hashes, `## Heading ##`, are stripped
+
+### Slugs
+
+Slugs are built from the rendered heading text with the same algorithm as GitHub, so the anchors work on github.com and in every renderer that follows it. See `slugify` and `headingText` above.
+
+## License
+
+MIT

package/bin/toc.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { buildToc, findMarkers, renderToc } from '../index.js';
+
+const USAGE = `Usage: toc [options] [file...]
+
+Update the table of contents between every <!-- toc --> and <!-- /toc -->
+pair in markdown files. Each pair lists the headings below its own start
+marker. A file without markers is skipped, and so is a pair that is
+unbalanced, has a problem on its start marker, or has no headings below
+it, each with a warning on stderr.
+
+Markers:
+  <!-- toc -->                          plain list
+  <!-- toc collapsible -->              list inside a <details> element, open
+  <!-- toc collapsed -->                same, but closed until clicked
+  <!-- toc collapsed="Contents" -->     either one with a custom summary text
+  <!-- toc collapsed class="toc" -->    other name="value" pairs go on <summary>
+  <!-- /toc -->                         end of the block Files are resolved against the current directory and default to
+README.md. Several files can be given as separate arguments or comma
+separated.
+
+Options:
+  -n, --dry-run  print the toc to stdout and report on stderr, write nothing.
+                 Without markers every heading is listed so the block can be
+                 pasted into the document
+  -h, --help     show this help
+`;
+
+await main();
+
+async function main() {
+  const { files, dryRun, help, unknown } = parseArgs(process.argv.slice(2));
+
+  if (unknown) {
+    console.error(`Unknown option: ${unknown}\n\n${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (help) {
+    console.log(USAGE);
+    return;
+  }
+
+  for (const file of files) {
+    try {
+      await processFile(file, dryRun);
+    } catch (err) {
+      console.error(`${file}: ${/** @type {Error} */ (err).message}`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+/**
+ * Status lines go to stdout, warnings to stderr with the marker's line number. With `dryRun` the rendered toc
+ * of every start marker goes to stdout instead of the file, so it can be piped, and the status line moves to
+ * stderr. A start marker that will be skipped still gets its block printed, plain when its options are broken,
+ * so the author sees the list either way.
+ * @param {string} file
+ * @param {boolean} dryRun
+ */
+async function processFile(file, dryRun) {
+  const source = await readFile(file, 'utf8');
+  const markers = findMarkers(source);
+  const warn = console.error;
+
+  if (markers.length === 0) {
+    const toc = renderToc(source);
+    if (dryRun && toc) console.log(toc);
+    warn(`${file}: no TOC markers, skipped.`);
+    return;
+  }
+
+  let updatable = 0;
+  for (const { start, end, options, problem } of markers) {
+    if (start === -1) {
+      warn(`${file}:${end + 1}: TOC end marker without start marker, skipped.`);
+      continue;
+    }
+    const toc = renderToc(source, start, problem ? {} : options);
+    if (dryRun && toc) console.log(toc);
+    if (problem) warn(`${file}:${start + 1}: ${problem}, skipped.`);
+    else if (end === -1) warn(`${file}:${start + 1}: TOC start marker without end marker, skipped.`);
+    else if (!toc) warn(`${file}:${start + 1}: no headings below TOC start marker, skipped.`);
+    else updatable++;
+  }
+  if (updatable === 0) return;
+
+  const updated = buildToc(source);
+  if (updated === source) {
+    (dryRun ? console.error : console.log)(`${file}: TOC already up to date.`);
+  } else if (dryRun) {
+    console.error(`${file}: would write TOC.`);
+  } else {
+    await writeFile(file, updated);
+    console.log(`${file}: wrote TOC.`);
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ files: string[], dryRun: boolean, help: boolean, unknown?: string }}
+ */
+function parseArgs(argv) {
+  /** @type {string[]} */
+  const files = [];
+  let dryRun = false;
+  let help = false;
+  for (const arg of argv) {
+    if (arg === '-n' || arg === '--dry-run') dryRun = true;
+    else if (arg === '-h' || arg === '--help') help = true;
+    else if (arg.startsWith('-')) return { files, dryRun, help, unknown: arg };
+    else files.push(...arg.split(',').filter(Boolean));
+  }
+  return { files: files.length ? files : ['README.md'], dryRun, help };
+}

package/index.cjs

@@ -0,0 +1,332 @@
+'use strict';
+
+const TOC_START = '<!-- toc -->';
+const TOC_END = '<!-- /toc -->';
+const DEFAULT_SUMMARY = 'Table of contents';
+const KNOWN_OPTIONS = ['collapsible', 'collapsed'];
+const NUL = String.fromCharCode(0);
+
+/**
+ * Return the markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated. Each
+ * pair lists every heading below its own start marker. A pair is left alone when it is unbalanced, has a
+ * problem on its start marker, or has no headings below it, and nothing outside the pairs is ever touched.
+ * The start marker line is kept as written, options included.
+ * @param {string} source
+ * @returns {string}
+ */
+function buildToc(source) {
+  const { lines, eol } = splitLines(source);
+  const { headlines, markers } = scan(lines);
+  /** @type {string[]} */
+  const out = [];
+  let cursor = 0;
+  for (const { start, end, options, problem } of markers) {
+    if (start === -1 || end === -1 || problem) continue;
+    const listed = headlines.filter((h) => h.line > start);
+    if (listed.length === 0) continue;
+    out.push(...lines.slice(cursor, start), renderBlock(listed, lines[start], options, eol));
+    cursor = end + 1;
+  }
+  out.push(...lines.slice(cursor));
+  return out.join(eol);
+}
+
+/**
+ * Return the toc block, markers included, for the headings below `fromLine`, by default every heading so the
+ * block can be pasted into a document without markers. Returns an empty string when there is nothing to list.
+ * @param {string} source
+ * @param {number} [fromLine] zero based line number, typically the start marker's
+ * @param {TocOptions} [options] rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+ * @returns {string}
+ */
+function renderToc(source, fromLine = -1, options = {}) {
+  const { lines, eol } = splitLines(source);
+  const listed = scan(lines).headlines.filter((h) => h.line > fromLine);
+  return listed.length === 0 ? '' : renderBlock(listed, formatMarker(options), options, eol);
+}
+
+/**
+ * Every marker pair in document order as zero based line numbers, outside fenced code blocks. A start marker
+ * pairs with the first end marker after it. A missing side is -1: a start marker without an end marker, or an
+ * end marker with no open start marker before it. `options` holds the recognised options written on the start
+ * marker and `problem`, only present when there is one, says why the marker cannot be used.
+ * @param {string} source
+ * @returns {Marker[]}
+ */
+function findMarkers(source) {
+  return scan(splitLines(source).lines).markers;
+}
+
+/**
+ * Slug a heading's rendered text the way github-slugger does: lowercase, drop everything that is not a
+ * letter, number, mark, space, hyphen or underscore, then turn each space into a hyphen. Nothing is trimmed
+ * or collapsed.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\p{M} _-]/gu, '')
+    .replace(/ /g, '-');
+}
+
+/**
+ * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+ * @param {string} markdown
+ * @returns {string}
+ */
+function headingText(markdown) {
+  const { text, restore } = protect(stripClosingHashes(markdown));
+  const rendered = stripLinks(text)
+    .replace(/<\/?[a-zA-Z][^>]*>/g, '')
+    .replace(/~~(?=\S)(.+?)(?<=\S)~~/g, '$1')
+    .replace(/\*+(?=\S)|(?<=\S)\*+/g, '')
+    .replace(/(?<![\p{L}\p{N}_])_+(?=\S)|(?<=\S)_+(?![\p{L}\p{N}_])/gu, '');
+  return restore(rendered).trim();
+}
+
+/**
+ * Split the source into lines and remember its line ending, CRLF when the source has any, so the toc is
+ * written the way the rest of the file is and a Windows authored file does not end up with mixed endings.
+ * @param {string} source
+ * @returns {{ lines: string[], eol: string }}
+ */
+function splitLines(source) {
+  return { lines: source.split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
+}
+
+/**
+ * Scan the lines for every marker pair and every ATX and setext heading, all outside fenced code blocks. A
+ * marker is a line holding nothing but the comment, indented at most three spaces like a heading, since four
+ * make an indented code block. A start marker, `<!-- toc -->` with optional options before the closing `-->`,
+ * opens a pair that the first end marker after it closes; a start marker inside an open pair is content and an end marker outside a pair is
+ * reported with start -1.
+ * @param {string[]} lines
+ * @returns {{ headlines: Array<{ line: number, level: number, markdown: string }>, markers: Marker[] }}
+ */
+function scan(lines) {
+  /** @type {Array<{ line: number, level: number, markdown: string }>} */
+  const headlines = [];
+  /** @type {Marker[]} */
+  const markers = [];
+  /** @type {{ char: string, length: number } | null} */
+  let fence = null;
+  /** @type {Marker | null} */
+  let open = null;
+
+  for (const [i, line] of lines.entries()) {
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence.char && fenceMatch[1].length >= fence.length && !fenceMatch[2].trim()) {
+        fence = null;
+      }
+      continue;
+    }
+    if (fenceMatch && !(fenceMatch[1][0] === '`' && fenceMatch[2].includes('`'))) {
+      fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
+      continue;
+    }
+
+    const startMatch = /^ {0,3}<!--\s*toc(?:\s+(.*?))?\s*-->\s*$/.exec(line);
+    if (startMatch) {
+      if (!open) markers.push((open = { start: i, end: -1, ...parseOptions(startMatch[1]) }));
+      continue;
+    }
+    if (/^ {0,3}<!--\s*\/toc\s*-->\s*$/.test(line)) {
+      if (open) open.end = i;
+      else markers.push({ start: -1, end: i, options: {} });
+      open = null;
+      continue;
+    }
+
+    const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (atx) {
+      headlines.push({ line: i, level: atx[1].length, markdown: atx[2] });
+      continue;
+    }
+
+    const setext = /^ {0,3}(=+|-+)\s*$/.exec(line);
+    if (setext && i > 0 && isParagraphText(lines[i - 1])) {
+      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim() });
+    }
+  }
+  return { headlines, markers };
+}
+
+/**
+ * The toc block for the given headings, wrapped in the given start marker line and the end marker. Indentation
+ * is relative to the shallowest level listed so far, so the list never starts indented, which markdown would
+ * render flat anyway, and duplicate slugs get github style `-1`, `-2` suffixes. With
+ * `collapsible` or `collapsed` the list goes inside a details element, open or closed to start with, blank
+ * lines around it so it renders as markdown, and any other attributes from the marker on the summary element.
+ * @param {Array<{ level: number, markdown: string }>} headlines
+ * @param {string} startLine the start marker as written in the document
+ * @param {TocOptions} options
+ * @param {string} [eol] line ending, LF by default
+ */
+function renderBlock(headlines, startLine, options, eol = '\n') {
+  /** @type {Record<string, number>} */
+  const occurrences = {};
+  let minLevel = Infinity;
+  const tocLines = headlines.map(({ level, markdown }) => {
+    minLevel = Math.min(minLevel, level);
+    const base = slugify(headingText(markdown));
+    let slug = base;
+    while (Object.hasOwn(occurrences, slug)) {
+      occurrences[base]++;
+      slug = `${base}-${occurrences[base]}`;
+    }
+    occurrences[slug] = 0;
+    return `${'  '.repeat(level - minLevel)}- [${headingLabel(markdown)}](#${slug})`;
+  });
+  const details = options.collapsible ?? options.collapsed;
+  if (details === undefined) return [startLine, '', ...tocLines, '', TOC_END].join(eol);
+  const summary = details === true ? DEFAULT_SUMMARY : details;
+  const tag = options.collapsible === undefined ? '<details>' : '<details open>';
+  const attrs = formatAttributes(options.attributes ?? {})
+    .map((a) => ` ${a}`)
+    .join('');
+  return [startLine, tag, `<summary${attrs}>${summary}</summary>`, '', ...tocLines, '', '</details>', TOC_END].join(eol);
+}
+
+/**
+ * Parse what is written on a start marker: the options as bare names (`collapsed`) or quoted values
+ * (`collapsed="Contents"`), and any other well-formed `name="value"` as an attribute for the summary element.
+ * Anything else, bare names that are not options, unquoted values, malformed names, is a problem, as is a
+ * combination that makes no sense. A marker with a problem is never used.
+ * @param {string | undefined} text
+ * @returns {{ options: TocOptions, problem?: string }}
+ */
+function parseOptions(text) {
+  /** @type {TocOptions} */
+  const options = {};
+  /** @type {Record<string, string>} */
+  const attributes = {};
+  /** @type {string[]} */
+  const unknown = [];
+  for (const [token, name, value] of (text ?? '').matchAll(/([^\s="]+)(?:="([^"]*)")?(?=\s|$)|\S+/g)) {
+    if (name && KNOWN_OPTIONS.includes(name)) options[/** @type {'collapsible' | 'collapsed'} */ (name)] = value ?? true;
+    else if (name && value !== undefined && /^[a-zA-Z][\w:.-]*$/.test(name)) attributes[name] = value;
+    else unknown.push(token);
+  }
+  const names = Object.keys(attributes);
+  if (names.length) options.attributes = attributes;
+  if (unknown.length) return { options, problem: `unknown TOC option ${unknown.join(' ')}` };
+  if (options.collapsible !== undefined && options.collapsed !== undefined) {
+    return { options, problem: 'TOC options collapsible and collapsed exclude each other' };
+  }
+  if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
+    return { options, problem: `TOC attributes ${names.join(', ')} need collapsible or collapsed` };
+  }
+  return { options };
+}
+
+/**
+ * The start marker line for the given options, the inverse of `parseOptions`: options first, then attributes.
+ * @param {TocOptions} options
+ */
+function formatMarker(options) {
+  const { attributes = {}, ...named } = options;
+  const parts = [
+    ...Object.entries(named).map(([name, value]) => (value === true ? name : `${name}="${value}"`)),
+    ...formatAttributes(attributes),
+  ];
+  return parts.length ? `<!-- toc ${parts.join(' ')} -->` : TOC_START;
+}
+
+/**
+ * @param {Record<string, string>} attributes
+ * @returns {string[]} `name="value"` in the order given
+ */
+function formatAttributes(attributes) {
+  return Object.entries(attributes).map(([name, value]) => `${name}="${value}"`);
+}
+
+/**
+ * The label used in the toc: the heading's own markdown, except that links become their text since a link
+ * cannot nest inside the toc link.
+ * @param {string} markdown
+ * @returns {string}
+ */
+function headingLabel(markdown) {
+  const { text, restore } = protect(stripClosingHashes(markdown), { keepCodeSpans: true });
+  return restore(stripLinks(text)).trim();
+}
+
+/**
+ * Replace code spans (with their content, or the whole span when `keepCodeSpans` is set) and backslash escapes
+ * (with the escaped character) by placeholders so the inline markdown passes leave them alone.
+ * @param {string} markdown
+ * @param {{ keepCodeSpans?: boolean }} [options]
+ */
+function protect(markdown, { keepCodeSpans = false } = {}) {
+  /** @type {string[]} */
+  const kept = [];
+  /** @param {string} value */
+  const keep = (value) => `${NUL}${kept.push(value) - 1}${NUL}`;
+  const text = markdown
+    .replace(/(`+)(.+?)\1(?!`)/g, (span, _ticks, code) => keep(keepCodeSpans ? span : unpadCodeSpan(code)))
+    .replace(/\\([!-/:-@[-`{-~])/g, (_, char) => keep(char));
+  return {
+    text,
+    /** @param {string} value */
+    restore: (value) => value.replace(new RegExp(`${NUL}(\\d+)${NUL}`, 'g'), (_, i) => kept[Number(i)]),
+  };
+}
+
+/**
+ * Strip one leading and one trailing space from code span content when both are present and the content is
+ * not only spaces, as CommonMark does.
+ * @param {string} code
+ */
+function unpadCodeSpan(code) {
+  if (code.length > 2 && code.startsWith(' ') && code.endsWith(' ') && code.trim() !== '') return code.slice(1, -1);
+  return code;
+}
+
+/** @param {string} markdown */
+function stripClosingHashes(markdown) {
+  return markdown.replace(/(^|\s+)#+\s*$/, '');
+}
+
+/**
+ * Links, images and reference links become their text, autolinks their url. Used for both the slug text and
+ * the toc label since a link cannot nest inside the toc link.
+ * @param {string} text
+ */
+function stripLinks(text) {
+  return text
+    .replace(/<(https?:\/\/[^>\s]+|mailto:[^>\s]+)>/g, '$1')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1');
+}
+
+/** @param {string} line */
+function isParagraphText(line) {
+  const trimmed = line.trim();
+  return trimmed !== '' && !/^(#|>|[-*+]\s|\d+[.)]\s|\||[-=]+\s*$|```|~~~|<!--)/.test(trimmed);
+}
+
+/**
+ * Options written on a start marker. `collapsible` wraps the list in a details element that starts open,
+ * `collapsed` in one that starts closed. Each is `true` for the default summary "Table of contents" or a
+ * string for a custom one. `attributes` are the other `name="value"` pairs on the marker, rendered on the
+ * summary element in the order written, only present when there are any.
+ * @typedef {{ collapsible?: true | string, collapsed?: true | string, attributes?: Record<string, string> }} TocOptions
+ */
+
+/**
+ * A marker pair. `start` and `end` are zero based line numbers, -1 when that side is missing. `problem` is
+ * only present when the start marker cannot be used: an unknown option or an impossible combination.
+ * @typedef {{ start: number, end: number, options: TocOptions, problem?: string }} Marker
+ */
+
+exports.TOC_END = TOC_END;
+exports.TOC_START = TOC_START;
+exports.buildToc = buildToc;
+exports.findMarkers = findMarkers;
+exports.headingText = headingText;
+exports.renderToc = renderToc;
+exports.slugify = slugify;

package/index.js

@@ -0,0 +1,322 @@
+export const TOC_START = '<!-- toc -->';
+export const TOC_END = '<!-- /toc -->';
+const DEFAULT_SUMMARY = 'Table of contents';
+const KNOWN_OPTIONS = ['collapsible', 'collapsed'];
+const NUL = String.fromCharCode(0);
+
+/**
+ * Return the markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated. Each
+ * pair lists every heading below its own start marker. A pair is left alone when it is unbalanced, has a
+ * problem on its start marker, or has no headings below it, and nothing outside the pairs is ever touched.
+ * The start marker line is kept as written, options included.
+ * @param {string} source
+ * @returns {string}
+ */
+export function buildToc(source) {
+  const { lines, eol } = splitLines(source);
+  const { headlines, markers } = scan(lines);
+  /** @type {string[]} */
+  const out = [];
+  let cursor = 0;
+  for (const { start, end, options, problem } of markers) {
+    if (start === -1 || end === -1 || problem) continue;
+    const listed = headlines.filter((h) => h.line > start);
+    if (listed.length === 0) continue;
+    out.push(...lines.slice(cursor, start), renderBlock(listed, lines[start], options, eol));
+    cursor = end + 1;
+  }
+  out.push(...lines.slice(cursor));
+  return out.join(eol);
+}
+
+/**
+ * Return the toc block, markers included, for the headings below `fromLine`, by default every heading so the
+ * block can be pasted into a document without markers. Returns an empty string when there is nothing to list.
+ * @param {string} source
+ * @param {number} [fromLine] zero based line number, typically the start marker's
+ * @param {TocOptions} [options] rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+ * @returns {string}
+ */
+export function renderToc(source, fromLine = -1, options = {}) {
+  const { lines, eol } = splitLines(source);
+  const listed = scan(lines).headlines.filter((h) => h.line > fromLine);
+  return listed.length === 0 ? '' : renderBlock(listed, formatMarker(options), options, eol);
+}
+
+/**
+ * Every marker pair in document order as zero based line numbers, outside fenced code blocks. A start marker
+ * pairs with the first end marker after it. A missing side is -1: a start marker without an end marker, or an
+ * end marker with no open start marker before it. `options` holds the recognised options written on the start
+ * marker and `problem`, only present when there is one, says why the marker cannot be used.
+ * @param {string} source
+ * @returns {Marker[]}
+ */
+export function findMarkers(source) {
+  return scan(splitLines(source).lines).markers;
+}
+
+/**
+ * Slug a heading's rendered text the way github-slugger does: lowercase, drop everything that is not a
+ * letter, number, mark, space, hyphen or underscore, then turn each space into a hyphen. Nothing is trimmed
+ * or collapsed.
+ * @param {string} text
+ * @returns {string}
+ */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\p{M} _-]/gu, '')
+    .replace(/ /g, '-');
+}
+
+/**
+ * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function headingText(markdown) {
+  const { text, restore } = protect(stripClosingHashes(markdown));
+  const rendered = stripLinks(text)
+    .replace(/<\/?[a-zA-Z][^>]*>/g, '')
+    .replace(/~~(?=\S)(.+?)(?<=\S)~~/g, '$1')
+    .replace(/\*+(?=\S)|(?<=\S)\*+/g, '')
+    .replace(/(?<![\p{L}\p{N}_])_+(?=\S)|(?<=\S)_+(?![\p{L}\p{N}_])/gu, '');
+  return restore(rendered).trim();
+}
+
+/**
+ * Split the source into lines and remember its line ending, CRLF when the source has any, so the toc is
+ * written the way the rest of the file is and a Windows authored file does not end up with mixed endings.
+ * @param {string} source
+ * @returns {{ lines: string[], eol: string }}
+ */
+function splitLines(source) {
+  return { lines: source.split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
+}
+
+/**
+ * Scan the lines for every marker pair and every ATX and setext heading, all outside fenced code blocks. A
+ * marker is a line holding nothing but the comment, indented at most three spaces like a heading, since four
+ * make an indented code block. A start marker, `<!-- toc -->` with optional options before the closing `-->`,
+ * opens a pair that the first end marker after it closes; a start marker inside an open pair is content and an end marker outside a pair is
+ * reported with start -1.
+ * @param {string[]} lines
+ * @returns {{ headlines: Array<{ line: number, level: number, markdown: string }>, markers: Marker[] }}
+ */
+function scan(lines) {
+  /** @type {Array<{ line: number, level: number, markdown: string }>} */
+  const headlines = [];
+  /** @type {Marker[]} */
+  const markers = [];
+  /** @type {{ char: string, length: number } | null} */
+  let fence = null;
+  /** @type {Marker | null} */
+  let open = null;
+
+  for (const [i, line] of lines.entries()) {
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence.char && fenceMatch[1].length >= fence.length && !fenceMatch[2].trim()) {
+        fence = null;
+      }
+      continue;
+    }
+    if (fenceMatch && !(fenceMatch[1][0] === '`' && fenceMatch[2].includes('`'))) {
+      fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
+      continue;
+    }
+
+    const startMatch = /^ {0,3}<!--\s*toc(?:\s+(.*?))?\s*-->\s*$/.exec(line);
+    if (startMatch) {
+      if (!open) markers.push((open = { start: i, end: -1, ...parseOptions(startMatch[1]) }));
+      continue;
+    }
+    if (/^ {0,3}<!--\s*\/toc\s*-->\s*$/.test(line)) {
+      if (open) open.end = i;
+      else markers.push({ start: -1, end: i, options: {} });
+      open = null;
+      continue;
+    }
+
+    const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (atx) {
+      headlines.push({ line: i, level: atx[1].length, markdown: atx[2] });
+      continue;
+    }
+
+    const setext = /^ {0,3}(=+|-+)\s*$/.exec(line);
+    if (setext && i > 0 && isParagraphText(lines[i - 1])) {
+      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim() });
+    }
+  }
+  return { headlines, markers };
+}
+
+/**
+ * The toc block for the given headings, wrapped in the given start marker line and the end marker. Indentation
+ * is relative to the shallowest level listed so far, so the list never starts indented, which markdown would
+ * render flat anyway, and duplicate slugs get github style `-1`, `-2` suffixes. With
+ * `collapsible` or `collapsed` the list goes inside a details element, open or closed to start with, blank
+ * lines around it so it renders as markdown, and any other attributes from the marker on the summary element.
+ * @param {Array<{ level: number, markdown: string }>} headlines
+ * @param {string} startLine the start marker as written in the document
+ * @param {TocOptions} options
+ * @param {string} [eol] line ending, LF by default
+ */
+function renderBlock(headlines, startLine, options, eol = '\n') {
+  /** @type {Record<string, number>} */
+  const occurrences = {};
+  let minLevel = Infinity;
+  const tocLines = headlines.map(({ level, markdown }) => {
+    minLevel = Math.min(minLevel, level);
+    const base = slugify(headingText(markdown));
+    let slug = base;
+    while (Object.hasOwn(occurrences, slug)) {
+      occurrences[base]++;
+      slug = `${base}-${occurrences[base]}`;
+    }
+    occurrences[slug] = 0;
+    return `${'  '.repeat(level - minLevel)}- [${headingLabel(markdown)}](#${slug})`;
+  });
+  const details = options.collapsible ?? options.collapsed;
+  if (details === undefined) return [startLine, '', ...tocLines, '', TOC_END].join(eol);
+  const summary = details === true ? DEFAULT_SUMMARY : details;
+  const tag = options.collapsible === undefined ? '<details>' : '<details open>';
+  const attrs = formatAttributes(options.attributes ?? {})
+    .map((a) => ` ${a}`)
+    .join('');
+  return [startLine, tag, `<summary${attrs}>${summary}</summary>`, '', ...tocLines, '', '</details>', TOC_END].join(eol);
+}
+
+/**
+ * Parse what is written on a start marker: the options as bare names (`collapsed`) or quoted values
+ * (`collapsed="Contents"`), and any other well-formed `name="value"` as an attribute for the summary element.
+ * Anything else, bare names that are not options, unquoted values, malformed names, is a problem, as is a
+ * combination that makes no sense. A marker with a problem is never used.
+ * @param {string | undefined} text
+ * @returns {{ options: TocOptions, problem?: string }}
+ */
+function parseOptions(text) {
+  /** @type {TocOptions} */
+  const options = {};
+  /** @type {Record<string, string>} */
+  const attributes = {};
+  /** @type {string[]} */
+  const unknown = [];
+  for (const [token, name, value] of (text ?? '').matchAll(/([^\s="]+)(?:="([^"]*)")?(?=\s|$)|\S+/g)) {
+    if (name && KNOWN_OPTIONS.includes(name)) options[/** @type {'collapsible' | 'collapsed'} */ (name)] = value ?? true;
+    else if (name && value !== undefined && /^[a-zA-Z][\w:.-]*$/.test(name)) attributes[name] = value;
+    else unknown.push(token);
+  }
+  const names = Object.keys(attributes);
+  if (names.length) options.attributes = attributes;
+  if (unknown.length) return { options, problem: `unknown TOC option ${unknown.join(' ')}` };
+  if (options.collapsible !== undefined && options.collapsed !== undefined) {
+    return { options, problem: 'TOC options collapsible and collapsed exclude each other' };
+  }
+  if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
+    return { options, problem: `TOC attributes ${names.join(', ')} need collapsible or collapsed` };
+  }
+  return { options };
+}
+
+/**
+ * The start marker line for the given options, the inverse of `parseOptions`: options first, then attributes.
+ * @param {TocOptions} options
+ */
+function formatMarker(options) {
+  const { attributes = {}, ...named } = options;
+  const parts = [
+    ...Object.entries(named).map(([name, value]) => (value === true ? name : `${name}="${value}"`)),
+    ...formatAttributes(attributes),
+  ];
+  return parts.length ? `<!-- toc ${parts.join(' ')} -->` : TOC_START;
+}
+
+/**
+ * @param {Record<string, string>} attributes
+ * @returns {string[]} `name="value"` in the order given
+ */
+function formatAttributes(attributes) {
+  return Object.entries(attributes).map(([name, value]) => `${name}="${value}"`);
+}
+
+/**
+ * The label used in the toc: the heading's own markdown, except that links become their text since a link
+ * cannot nest inside the toc link.
+ * @param {string} markdown
+ * @returns {string}
+ */
+function headingLabel(markdown) {
+  const { text, restore } = protect(stripClosingHashes(markdown), { keepCodeSpans: true });
+  return restore(stripLinks(text)).trim();
+}
+
+/**
+ * Replace code spans (with their content, or the whole span when `keepCodeSpans` is set) and backslash escapes
+ * (with the escaped character) by placeholders so the inline markdown passes leave them alone.
+ * @param {string} markdown
+ * @param {{ keepCodeSpans?: boolean }} [options]
+ */
+function protect(markdown, { keepCodeSpans = false } = {}) {
+  /** @type {string[]} */
+  const kept = [];
+  /** @param {string} value */
+  const keep = (value) => `${NUL}${kept.push(value) - 1}${NUL}`;
+  const text = markdown
+    .replace(/(`+)(.+?)\1(?!`)/g, (span, _ticks, code) => keep(keepCodeSpans ? span : unpadCodeSpan(code)))
+    .replace(/\\([!-/:-@[-`{-~])/g, (_, char) => keep(char));
+  return {
+    text,
+    /** @param {string} value */
+    restore: (value) => value.replace(new RegExp(`${NUL}(\\d+)${NUL}`, 'g'), (_, i) => kept[Number(i)]),
+  };
+}
+
+/**
+ * Strip one leading and one trailing space from code span content when both are present and the content is
+ * not only spaces, as CommonMark does.
+ * @param {string} code
+ */
+function unpadCodeSpan(code) {
+  if (code.length > 2 && code.startsWith(' ') && code.endsWith(' ') && code.trim() !== '') return code.slice(1, -1);
+  return code;
+}
+
+/** @param {string} markdown */
+function stripClosingHashes(markdown) {
+  return markdown.replace(/(^|\s+)#+\s*$/, '');
+}
+
+/**
+ * Links, images and reference links become their text, autolinks their url. Used for both the slug text and
+ * the toc label since a link cannot nest inside the toc link.
+ * @param {string} text
+ */
+function stripLinks(text) {
+  return text
+    .replace(/<(https?:\/\/[^>\s]+|mailto:[^>\s]+)>/g, '$1')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1');
+}
+
+/** @param {string} line */
+function isParagraphText(line) {
+  const trimmed = line.trim();
+  return trimmed !== '' && !/^(#|>|[-*+]\s|\d+[.)]\s|\||[-=]+\s*$|```|~~~|<!--)/.test(trimmed);
+}
+
+/**
+ * Options written on a start marker. `collapsible` wraps the list in a details element that starts open,
+ * `collapsed` in one that starts closed. Each is `true` for the default summary "Table of contents" or a
+ * string for a custom one. `attributes` are the other `name="value"` pairs on the marker, rendered on the
+ * summary element in the order written, only present when there are any.
+ * @typedef {{ collapsible?: true | string, collapsed?: true | string, attributes?: Record<string, string> }} TocOptions
+ */
+
+/**
+ * A marker pair. `start` and `end` are zero based line numbers, -1 when that side is missing. `problem` is
+ * only present when the start marker cannot be used: an unknown option or an impossible combination.
+ * @typedef {{ start: number, end: number, options: TocOptions, problem?: string }} Marker
+ */

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@0dep/toc",
+  "version": "0.0.1",
+  "description": "Generate a GitHub flavoured markdown table of contents",
+  "type": "module",
+  "sideEffects": false,
+  "module": "./index.js",
+  "main": "./index.cjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./index.cjs",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "toc": "bin/toc.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "pretest": "npm run toc && npm run dist",
+    "test": "mocha",
+    "posttest": "npm run lint && npm run tsc && npm run test:md",
+    "test:md": "texample",
+    "toc": "node bin/toc.js README.md",
+    "posttoc": "prettier --write README.md",
+    "lint": "eslint . --cache && prettier . --check --cache",
+    "tsc": "tsc -p test",
+    "dist": "rollup -c && dts-buddy",
+    "prepack": "npm run dist",
+    "cov:html": "c8 -r html -r text mocha",
+    "test:lcov": "c8 -r lcov mocha && npm run lint"
+  },
+  "c8": {
+    "include": [
+      "index.js",
+      "bin/"
+    ]
+  },
+  "keywords": [
+    "toc",
+    "table of contents",
+    "markdown",
+    "readme",
+    "github",
+    "slug"
+  ],
+  "author": {
+    "name": "Zerodep AB",
+    "url": "https://0dep.se"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerodep/toc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zerodep/toc/issues"
+  },
+  "homepage": "https://0dep.se/tools",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.20.2",
+    "c8": "^12.0.0",
+    "chai": "^6.2.2",
+    "dts-buddy": "^0.8.3",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "mocha": "^12.0.0",
+    "prettier": "^3.9.6",
+    "rollup": "^4.63.1",
+    "texample": "^1.0.2",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "bin/",
+    "index.js",
+    "index.cjs",
+    "types/index.d.ts*",
+    "CHANGELOG.md"
+  ]
+}

package/types/index.d.ts

@@ -0,0 +1,60 @@
+declare module '@0dep/toc' {
+	/**
+	 * Return the markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated. Each
+	 * pair lists every heading below its own start marker. A pair is left alone when it is unbalanced, has a
+	 * problem on its start marker, or has no headings below it, and nothing outside the pairs is ever touched.
+	 * The start marker line is kept as written, options included.
+	 * */
+	export function buildToc(source: string): string;
+	/**
+	 * Return the toc block, markers included, for the headings below `fromLine`, by default every heading so the
+	 * block can be pasted into a document without markers. Returns an empty string when there is nothing to list.
+	 * @param fromLine zero based line number, typically the start marker's
+	 * @param options rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+	 * */
+	export function renderToc(source: string, fromLine?: number, options?: TocOptions): string;
+	/**
+	 * Every marker pair in document order as zero based line numbers, outside fenced code blocks. A start marker
+	 * pairs with the first end marker after it. A missing side is -1: a start marker without an end marker, or an
+	 * end marker with no open start marker before it. `options` holds the recognised options written on the start
+	 * marker and `problem`, only present when there is one, says why the marker cannot be used.
+	 * */
+	export function findMarkers(source: string): Marker[];
+	/**
+	 * Slug a heading's rendered text the way github-slugger does: lowercase, drop everything that is not a
+	 * letter, number, mark, space, hyphen or underscore, then turn each space into a hyphen. Nothing is trimmed
+	 * or collapsed.
+	 * */
+	export function slugify(text: string): string;
+	/**
+	 * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+	 * */
+	export function headingText(markdown: string): string;
+	export const TOC_START: "<!-- toc -->";
+	export const TOC_END: "<!-- /toc -->";
+	/**
+	 * Options written on a start marker. `collapsible` wraps the list in a details element that starts open,
+	 * `collapsed` in one that starts closed. Each is `true` for the default summary "Table of contents" or a
+	 * string for a custom one. `attributes` are the other `name="value"` pairs on the marker, rendered on the
+	 * summary element in the order written, only present when there are any.
+	 */
+	export type TocOptions = {
+		collapsible?: true | string;
+		collapsed?: true | string;
+		attributes?: Record<string, string>;
+	};
+	/**
+	 * A marker pair. `start` and `end` are zero based line numbers, -1 when that side is missing. `problem` is
+	 * only present when the start marker cannot be used: an unknown option or an impossible combination.
+	 */
+	export type Marker = {
+		start: number;
+		end: number;
+		options: TocOptions;
+		problem?: string;
+	};
+
+	export {};
+}
+
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1,23 @@
+{
+	"version": 3,
+	"file": "index.d.ts",
+	"names": [
+		"buildToc",
+		"renderToc",
+		"findMarkers",
+		"slugify",
+		"headingText",
+		"TOC_START",
+		"TOC_END",
+		"TocOptions",
+		"Marker"
+	],
+	"sources": [
+		"../index.js"
+	],
+	"sourcesContent": [
+		null
+	],
+	"mappings": ";;;;;;;iBAcgBA,QAAQA;;;;;;;iBAyBRC,SAASA;;;;;;;iBAcTC,WAAWA;;;;;;iBAWXC,OAAOA;;;;iBAYPC,WAAWA;cA5EdC,SAASA;cACTC,OAAOA;;;;;;;aAyT0FC,UAAUA;;;;;;;;;aAMpCC,MAAMA",
+	"ignoreList": []
+}