@0dep/toc 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+<!-- toc levels="2" -->
+
+- [v2.0.0 - 2026-09-18](#v200---2026-09-18)
+- [v1.1.0 - 2026-09-17](#v110---2026-09-17)
+- [v1.0.1 - 2026-09-12](#v101---2026-09-12)
+- [v1.0.0 - 2026-09-12](#v100---2026-09-12)
+- [v0.0.1 - 2026-09-12](#v001---2026-09-12)
+
+<!-- /toc -->
+
+## v2.0.0 - 2026-09-18
+
+### Breaking
+
+- Node 22.12 or later. The bin expands glob patterns with `fs.promises.glob`, and `require('@0dep/toc')` loads `index.js` itself, so the CommonJS bundle `index.cjs` is gone
+- `types/index.d.ts` is emitted by `tsc` as a plain module declaration instead of the `declare module '@0dep/toc'` block dts-buddy wrote, with a declaration map back to `index.js`
+
+### Added
+
+- `levels="2"`, `levels="2-3"`, `levels="-3"` or `levels="3-"` on the start marker limits the toc to those heading levels, so a changelog can list its versions alone. A broken value is ignored with a warning, `findMarkers` reports it as `warning`. `renderToc` takes `{ levels: '2-3' }`
+- an argument with `*`, `?` or `[` is a glob pattern, `**` matches subdirectories and `node_modules` is never entered, so `toc 'docs/**/*.md'` works the same in an npm script on Windows as on macOS and Linux. A pattern that matches nothing is skipped with a warning, and a file is processed once however many arguments name or match it
+- `-s`/`--silent` drops the status lines and the skipped warnings from the bin, so only anchor warnings and errors are written
+- a file that does not exist is skipped with a warning and no longer sets the exit code, like a file without markers. `--silent` keeps that warning
+
 ## v1.1.0 - 2026-09-17
 
 - duplicate slugs are numbered over the whole document, headings above the start marker included, the way GitHub does. A toc under a heading that shares its name with a later heading used to link the later one without the `-1`

package/README.md

@@ -2,7 +2,7 @@
 
 [![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.
+Generate a GitHub flavoured table of contents for markdown files. No dependencies. The library is string in, string out and runs in the browser too. Node 22.12 or later for the `toc` bin and for `require`.
 
 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, and every link to an anchor in the document is checked against them.
 
@@ -12,6 +12,9 @@ The toc is written between `<!-- toc -->` and `<!-- /toc -->` markers, and only
 - [Markers](#markers)
   - [Several tocs in one document](#several-tocs-in-one-document)
   - [Options](#options)
+    - [`collapsible` and `collapsed`](#collapsible-and-collapsed)
+    - [Summary attributes](#summary-attributes)
+    - [`levels`](#levels)
   - [What is left alone](#what-is-left-alone)
 - [CLI](#cli)
   - [Options](#options-1)
@@ -101,6 +104,18 @@ The top toc lists API, get, set and License. The toc under API lists get, set an
 
 ### Options
 
+The start marker takes options, bare or as `name="value"`, in any order. It is kept exactly as written, and spacing inside the comment does not matter. Anything on it that is not one of the three options or a well-formed attribute makes the pair skip with a warning rather than guess: a bare name other than the options, so a typo like `collapsable` is caught, an unquoted value like `collapsed=yes`, both details options at once, or attributes without an option to give them a summary element.
+
+<!-- toc levels="4" -->
+
+- [`collapsible` and `collapsed`](#collapsible-and-collapsed)
+- [Summary attributes](#summary-attributes)
+- [`levels`](#levels)
+
+<!-- /toc -->
+
+#### `collapsible` and `collapsed`
+
 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
@@ -122,7 +137,11 @@ becomes
 <!-- /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:
+Both take a summary text, `<!-- toc collapsible="Contents" -->` or `<!-- toc collapsed="Contents" -->`.
+
+#### Summary attributes
+
+Any other `name="value"` pair on the start marker is put on the summary element, in the order written:
 
 ```markdown
 <!-- toc collapsed="Contents" title="Click to expand" style="font-weight: bold" -->
@@ -135,9 +154,29 @@ Both take a summary text, `<!-- toc collapsible="Contents" -->` or `<!-- toc col
 <!-- /toc -->
 ```
 
-Renderers sanitise html, so check what yours keeps. GitHub drops `style`, `class` and `id` but keeps `title`, `dir`, `lang`, `role` and `aria-*` attributes, so in the example above only the `title` survives there. The start marker itself is kept exactly as written, and spacing inside the comment does not matter.
+Renderers sanitise html, so check what yours keeps. GitHub drops `style`, `class` and `id` but keeps `title`, `dir`, `lang`, `role` and `aria-*` attributes, so in the example above only the `title` survives there.
+
+#### `levels`
+
+`levels` limits the toc to a heading level or a range of levels, `levels="2"`, `levels="2-3"`, `levels="-3"` for everything up to `###` or `levels="3-"` for `###` and deeper. The levels are the heading's own, the number of `#`, wherever the marker sits, so a toc under `## API` that should list the `###` headings beneath it says `levels="3"`. The list starts flat at the shallowest level listed, so a changelog with `### Added` and `### Breaking` under every version gets a toc of the versions alone:
+
+```markdown
+<!-- toc levels="2" collapsed="Versions" -->
+<details>
+<summary>Versions</summary>
+
+- [v2.0.0 - 2026-09-18](#v200---2026-09-18)
+- [v1.1.0 - 2026-09-17](#v110---2026-09-17)
+
+</details>
+<!-- /toc -->
+
+## v2.0.0 - 2026-09-18
+
+### Breaking
+```
 
-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.
+A `levels` value that is not a level or a range between 1 and 6 is ignored with a warning, and the pair lists every level. The toc above, under Options, is a `levels="4"` one: without it every heading to the end of this file would be listed.
 
 ### What is left alone
 
@@ -159,20 +198,23 @@ This README has two headings named Options, the one above and the one under CLI.
 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 'docs/**/*.md'         # glob patterns, quoted so the shell leaves them alone
 npx toc --dry-run README.md    # print the toc, write nothing
 npx toc --check README.md      # exit with 1 when a link to an anchor has no target
+npx toc -c -s docs/*.md        # write only the anchor warnings
 npx toc --help
 ```
 
-Paths are resolved against the current directory.
+Paths are resolved against the current directory. An argument with `*`, `?` or `[` is a glob pattern, expanded by the bin with Node's own `fs.glob`, so it works the same in an npm script on Windows, where the shell does not expand it, as on macOS and Linux. `**` matches subdirectories, `node_modules` is never entered, and the matches are processed in sorted order. A pattern that matches nothing is skipped with a warning. A file is processed once, however many arguments name or match it.
 
 ### Options
 
-| Option          | Effect                                                                        |
-| --------------- | ----------------------------------------------------------------------------- |
-| `-n, --dry-run` | Print the toc of every pair to stdout and the status to stderr, write nothing |
-| `-c, --check`   | Exit with 1 when a link to an anchor has no target                            |
-| `-h, --help`    | Show usage                                                                    |
+| Option          | Effect                                                                                         |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| `-n, --dry-run` | Print the toc of every pair to stdout and the status to stderr, write nothing                  |
+| `-c, --check`   | Exit with 1 when a link to an anchor has no target                                             |
+| `-s, --silent`  | Skip the status lines and the skipped warnings, keep missing files, anchor warnings and errors |
+| `-h, --help`    | Show usage                                                                                     |
 
 ### Output and exit code
 
@@ -182,6 +224,8 @@ One status line per file on stdout, and one warning per skipped file or pair on
 | --------------------------------------------------------------------------------- | ------ | ---------------------------------------------------- |
 | `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 such file, skipped.`                                               | stderr | The file does not exist                              |
+| `docs/*.md: no matching file, skipped.`                                           | stderr | The pattern matched nothing                          |
 | `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                                      |
@@ -189,9 +233,10 @@ One status line per file on stdout, and one warning per skipped file or pair on
 | `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:3: TOC option levels "x" is not a level or a range like 2-3, ignored.` | stderr | Every level is listed instead                        |
 | `README.md:9: anchor #instal has no target.`                                      | stderr | A link points at a heading that does not exist       |
 | `README.md:9: anchor #Install has no target, did you mean #install?`              | stderr | Same, and a heading obviously matches                |
-| `README.md: ENOENT: no such file or directory, ...`                               | stderr | The file could not be read or written                |
+| `README.md: EISDIR: illegal operation on a directory, ...`                        | stderr | The file could not be read or written                |
 
 The exit code is 1 when a file could not be read or written, when an option is not recognised, or, with `--check`, when a link to an anchor has no target. Otherwise 0. Skipped files and pairs do not affect the exit code.
 
@@ -205,6 +250,12 @@ The warning ends with `did you mean` when the target is obvious: slugging the an
 npx toc --check docs/*.md
 ```
 
+With `--silent` the status lines and the skipped warnings are dropped, so the output is the missing files, the anchor warnings and the errors alone. In a dry run the toc blocks are still printed to stdout.
+
+```sh
+npx toc --check --silent docs/*.md
+```
+
 ### 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.
@@ -260,7 +311,7 @@ To regenerate the toc and format the rest of the file in one go, let a `posttoc`
 import { buildToc, renderToc, findMarkers, findAnchors, slugify, headingText, TOC_START, TOC_END } from '@0dep/toc';
 ```
 
-CommonJS works the same way with `require('@0dep/toc')`.
+CommonJS works the same way with `require('@0dep/toc')`, there is no separate bundle since Node 22.12 requires ES modules natively.
 
 ### `buildToc(source)`
 
@@ -290,7 +341,7 @@ console.log(md);
 
 ### `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.
+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' } }`, `{ levels: '2-3' }` and so on.
 
 ```javascript
 import { renderToc } from '@0dep/toc';
@@ -310,7 +361,7 @@ console.log(renderToc('# Title\n\n## Install\n\n### From npm\n'));
 
 ### `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.
+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. When an option on it is ignored, a broken `levels` value, `warning` says so.
 
 ```javascript
 import { findMarkers } from '@0dep/toc';
@@ -389,6 +440,14 @@ The marker strings, `<!-- toc -->` and `<!-- /toc -->`, for code that wants to l
 </details>
 <!-- /toc -->
 
+And one with `levels="2"`, which lists only the level 2 headings that follow:
+
+<!-- toc levels="2" -->
+
+- [License](#license)
+
+<!-- /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 `---`

package/bin/toc.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /* eslint-disable no-console */
-import { readFile, writeFile } from 'node:fs/promises';
+import { glob, readFile, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
 
 import { buildToc, findAnchors, findMarkers, renderToc } from '../index.js';
 
@@ -8,9 +9,9 @@ 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. Every link to an anchor, [text](#slug),
+marker. A file that does not exist or has no 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. Every link to an anchor, [text](#slug),
 is checked against the headings and html ids in the file and a link
 without a target gets a warning too.
 
@@ -20,17 +21,23 @@ Markers:
   <!-- 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 levels="2-3" -->             only these heading levels, also "2", "-3", "3-"
   <!-- /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.
+separated. An argument with *, ? or [ is a glob pattern, ** matches
+subdirectories, node_modules is never entered. A pattern that matches
+nothing is skipped with a warning. A file is processed once, however
+many arguments name or match it.
 
 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
   -c, --check    exit with 1 when a link to an anchor has no target
+  -s, --silent   skip the status lines and the skipped warnings, only missing
+                 files, anchor warnings and errors are written
   -h, --help     show this help
 `;
 
@@ -49,27 +56,51 @@ async function main() {
     return;
   }
 
-  for (const file of files) {
-    try {
-      await processFile(file, flags);
-    } catch (err) {
-      console.error(`${file}: ${/** @type {Error} */ (err).message}`);
-      process.exitCode = 1;
+  const seen = new Set();
+  for (const arg of files) {
+    const matches = await expand(arg);
+    if (!matches.length) console.error(`${arg}: no matching file, skipped.`);
+    for (const file of matches) {
+      const key = resolve(file);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      try {
+        await processFile(file, flags);
+      } catch (err) {
+        if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+          console.error(`${file}: no such file, skipped.`);
+          continue;
+        }
+        console.error(`${file}: ${/** @type {Error} */ (err).message}`);
+        process.exitCode = 1;
+      }
     }
   }
 }
 
+/**
+ * Expand a glob pattern to the sorted matching files, a plain path is returned as is.
+ * @param {string} arg
+ * @returns {Promise<string[]>}
+ */
+async function expand(arg) {
+  if (!/[*?[]/.test(arg)) return [arg];
+  const matches = [];
+  for await (const file of glob(arg, { exclude: (path) => basename(path) === 'node_modules' })) matches.push(file);
+  return matches.sort();
+}
+
 /**
  * Update the toc and check the anchors of one file, or report what would happen with `dryRun`.
  * @param {string} file
- * @param {{ dryRun: boolean, check: boolean }} flags
+ * @param {{ dryRun: boolean, check: boolean, silent: boolean }} flags
  */
-async function processFile(file, { dryRun, check }) {
+async function processFile(file, { dryRun, check, silent }) {
   const source = await readFile(file, 'utf8');
-  const status = dryRun ? console.error : console.log;
+  const status = silent ? noop : dryRun ? console.error : console.log;
   const warn = console.error;
 
-  const regenerated = reportMarkers(file, source, dryRun);
+  const regenerated = reportMarkers(file, source, dryRun, silent);
   let updated = source;
   if (regenerated.length) {
     updated = buildToc(source);
@@ -91,11 +122,12 @@ async function processFile(file, { dryRun, check }) {
  * @param {string} file
  * @param {string} source
  * @param {boolean} dryRun
+ * @param {boolean} silent
  * @returns {Array<{ start: number, end: number }>}
  */
-function reportMarkers(file, source, dryRun) {
+function reportMarkers(file, source, dryRun, silent) {
   const markers = findMarkers(source);
-  const warn = console.error;
+  const warn = silent ? noop : console.error;
   /** @type {Array<{ start: number, end: number }>} */
   const regenerated = [];
 
@@ -106,11 +138,12 @@ function reportMarkers(file, source, dryRun) {
     return regenerated;
   }
 
-  for (const { start, end, options, problem } of markers) {
+  for (const { start, end, options, problem, warning } of markers) {
     if (start === -1) {
       warn(`${file}:${end + 1}: TOC end marker without start marker, skipped.`);
       continue;
     }
+    if (warning) warn(`${file}:${start + 1}: ${warning}.`);
     const toc = renderToc(source, start, problem ? {} : options);
     if (dryRun && toc) console.log(toc);
     if (problem) warn(`${file}:${start + 1}: ${problem}, skipped.`);
@@ -123,18 +156,21 @@ function reportMarkers(file, source, dryRun) {
 
 /**
  * @param {string[]} argv
- * @returns {{ files: string[], dryRun: boolean, check: boolean, help: boolean, unknown?: string }}
+ * @returns {{ files: string[], dryRun: boolean, check: boolean, silent: boolean, help: boolean, unknown?: string }}
  */
 function parseArgs(argv) {
   /** @type {string[]} */
   const files = [];
-  const flags = { dryRun: false, check: false, help: false };
+  const flags = { dryRun: false, check: false, silent: false, help: false };
   for (const arg of argv) {
     if (arg === '-n' || arg === '--dry-run') flags.dryRun = true;
     else if (arg === '-c' || arg === '--check') flags.check = true;
+    else if (arg === '-s' || arg === '--silent') flags.silent = true;
     else if (arg === '-h' || arg === '--help') flags.help = true;
     else if (arg.startsWith('-')) return { files, ...flags, unknown: arg };
     else files.push(...arg.split(',').filter(Boolean));
   }
   return { files: files.length ? files : ['README.md'], ...flags };
 }
+
+function noop() {}

package/index.js

@@ -1,7 +1,8 @@
 export const TOC_START = '<!-- toc -->';
 export const TOC_END = '<!-- /toc -->';
 const DEFAULT_SUMMARY = 'Table of contents';
-const KNOWN_OPTIONS = ['collapsible', 'collapsed'];
+const KNOWN_OPTIONS = ['collapsible', 'collapsed', 'levels'];
+const LEVELS = /^(?:([1-6])|([1-6])-([1-6])|([1-6])-|-([1-6]))$/;
 const NUL = String.fromCharCode(0);
 /** @type {Map<string, ReturnType<typeof analyse>>} */
 const cache = new Map();
@@ -19,7 +20,7 @@ export function buildToc(source) {
   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);
+    const listed = headingsBelow(headlines, start, options);
     if (listed.length === 0) continue;
     out.push(...lines.slice(cursor, start), renderBlock(listed, lines[start], options, eol));
     cursor = end + 1;
@@ -37,7 +38,7 @@ export function buildToc(source) {
  */
 export function renderToc(source, fromLine = -1, options = {}) {
   const { eol, headlines } = analyse(source);
-  const listed = headlines.filter((h) => h.line > fromLine);
+  const listed = headingsBelow(headlines, fromLine, options);
   return listed.length === 0 ? '' : renderBlock(listed, formatMarker(options), options, eol);
 }
 
@@ -242,6 +243,33 @@ function assignSlugs(headlines) {
   }
 }
 
+/**
+ * The headings after `fromLine` within the levels the options allow.
+ * @param {Headline[]} headlines
+ * @param {number} fromLine
+ * @param {TocOptions} options
+ * @returns {Headline[]}
+ */
+function headingsBelow(headlines, fromLine, options) {
+  const [min, max] = levelRange(options.levels) ?? [1, 6];
+  return headlines.filter((h) => h.line > fromLine && h.level >= min && h.level <= max);
+}
+
+/**
+ * The lowest and highest heading level a levels option allows, every level when absent, undefined when broken.
+ * @param {string} [levels]
+ * @returns {[number, number] | undefined}
+ */
+function levelRange(levels) {
+  if (levels === undefined) return [1, 6];
+  const match = LEVELS.exec(levels);
+  if (!match) return undefined;
+  const [, only, from, to, fromOpen, toOpen] = match;
+  const min = Number(only ?? from ?? fromOpen ?? 1);
+  const max = Number(only ?? to ?? toOpen ?? 6);
+  return min <= max ? [min, max] : undefined;
+}
+
 /**
  * The toc block for the headings, between the start marker line and the end marker.
  * @param {Headline[]} headlines
@@ -266,9 +294,9 @@ function renderBlock(headlines, startLine, options, eol = '\n') {
 }
 
 /**
- * The options written on a start marker, with a problem when they cannot be used.
+ * The options written on a start marker, with a problem when they cannot be used and a warning when one is ignored.
  * @param {string | undefined} text
- * @returns {{ options: TocOptions, problem?: string }}
+ * @returns {{ options: TocOptions, problem?: string, warning?: string }}
  */
 function parseOptions(text) {
   /** @type {TocOptions} */
@@ -278,20 +306,25 @@ function parseOptions(text) {
   /** @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;
+    if (name === 'levels') options.levels = value ?? '';
+    else 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' };
+  /** @type {{ options: TocOptions, problem?: string, warning?: string }} */
+  const parsed = { options };
+  if (options.levels !== undefined && !levelRange(options.levels)) {
+    parsed.warning = `TOC option levels "${options.levels}" is not a level or a range like 2-3, ignored`;
   }
-  if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
-    return { options, problem: `TOC attributes ${names.join(', ')} need collapsible or collapsed` };
+  if (unknown.length) parsed.problem = `unknown TOC option ${unknown.join(' ')}`;
+  else if (options.collapsible !== undefined && options.collapsed !== undefined) {
+    parsed.problem = 'TOC options collapsible and collapsed exclude each other';
+  } else if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
+    parsed.problem = `TOC attributes ${names.join(', ')} need collapsible or collapsed`;
   }
-  return { options };
+  return parsed;
 }
 
 /**
@@ -379,7 +412,7 @@ function isParagraphText(line) {
 
 /**
  * Options written on a start marker, each `true` or a summary text, and the other attributes for the summary element.
- * @typedef {{ collapsible?: true | string, collapsed?: true | string, attributes?: Record<string, string> }} TocOptions
+ * @typedef {{ collapsible?: true | string, collapsed?: true | string, levels?: string, attributes?: Record<string, string> }} TocOptions
  */
 
 /**
@@ -394,6 +427,6 @@ function isParagraphText(line) {
  */
 
 /**
- * A marker pair as zero based lines, -1 for a missing side, with its options and a problem when they cannot be used.
- * @typedef {{ start: number, end: number, options: TocOptions, problem?: string }} Marker
+ * A marker pair as zero based lines, -1 for a missing side, with its options, a problem when they cannot be used and a warning when one is ignored.
+ * @typedef {{ start: number, end: number, options: TocOptions, problem?: string, warning?: string }} Marker
  */

package/package.json

@@ -1,36 +1,34 @@
 {
   "name": "@0dep/toc",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "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"
+      "default": "./index.js"
     }
   },
   "bin": {
     "toc": "bin/toc.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "scripts": {
-    "pretest": "npm run toc && npm run dist",
+    "pretest": "npm run toc && npm run types",
     "test": "mocha",
     "posttest": "npm run lint && npm run tsc && npm run test:md",
     "test:md": "texample",
-    "toc": "node bin/toc.js --check README.md",
-    "posttoc": "prettier --write README.md",
+    "toc": "node bin/toc.js --check README.md CHANGELOG.md",
+    "posttoc": "prettier --write README.md CHANGELOG.md",
     "lint": "eslint . --cache && prettier . --check --cache",
     "tsc": "tsc -p test",
-    "dist": "rollup -c && dts-buddy",
-    "prepack": "npm run dist",
+    "types": "tsc",
+    "prepack": "npm run types",
     "cov:html": "c8 -r html -r text mocha",
     "test:lcov": "c8 -r lcov mocha && npm run lint"
   },
@@ -46,7 +44,8 @@
     "markdown",
     "readme",
     "github",
-    "slug"
+    "slug",
+    "glob"
   ],
   "author": {
     "name": "Zerodep AB",
@@ -63,26 +62,22 @@
   "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*",
+    "types/",
     "CHANGELOG.md"
   ]
 }

package/types/index.d.ts

@@ -1,70 +1,80 @@
-declare module '@0dep/toc' {
-	/**
-	 * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
-	 * */
-	export function buildToc(source: string): string;
-	/**
-	 * The toc block, markers included, for the headings below `fromLine`, empty when there is nothing to list.
-	 * @param fromLine zero based
-	 * */
-	export function renderToc(source: string, fromLine?: number, options?: TocOptions): string;
-	/**
-	 * Every marker pair in document order, shared with later calls for the same source.
-	 * */
-	export function findMarkers(source: string): Marker[];
-	/**
-	 * Every link to an anchor in the document, in order, shared with later calls for the same source.
-	 * */
-	export function findAnchors(source: string): Anchor[];
-	/**
-	 * The GitHub anchor slug of a heading's rendered text.
-	 * */
-	export function slugify(text: string): string;
-	/**
-	 * The text GitHub renders for a heading's inline markdown.
-	 * */
-	export function headingText(markdown: string): string;
-	export const TOC_START: "<!-- toc -->";
-	export const TOC_END: "<!-- /toc -->";
-	/**
-	 * Options written on a start marker, each `true` or a summary text, and the other attributes for the summary element.
-	 */
-	export type TocOptions = {
-		collapsible?: true | string;
-		collapsed?: true | string;
-		attributes?: Record<string, string>;
-	};
-	/**
-	 * A heading with its zero based line, level, inline markdown and GitHub slug.
-	 */
-	export type Headline = {
-		line: number;
-		level: number;
-		markdown: string;
-		slug: string;
-	};
-	/**
-	 * A link to an anchor with its zero based line, text, anchor as written, whether it has a target and, when it
-	 * has none and one heading clearly matches, a suggestion.
-	 */
-	export type Anchor = {
-		line: number;
-		text: string;
-		anchor: string;
-		valid: boolean;
-		suggestion?: string;
-	};
-	/**
-	 * A marker pair as zero based lines, -1 for a missing side, with its options and a problem when they cannot be used.
-	 */
-	export type Marker = {
-		start: number;
-		end: number;
-		options: TocOptions;
-		problem?: string;
-	};
-
-	export {};
-}
-
+/**
+ * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
+ * @param {string} source
+ * @returns {string}
+ */
+export function buildToc(source: string): string;
+/**
+ * The toc block, markers included, for the headings below `fromLine`, empty when there is nothing to list.
+ * @param {string} source
+ * @param {number} [fromLine] zero based
+ * @param {TocOptions} [options]
+ * @returns {string}
+ */
+export function renderToc(source: string, fromLine?: number, options?: TocOptions): string;
+/**
+ * Every marker pair in document order, shared with later calls for the same source.
+ * @param {string} source
+ * @returns {Marker[]}
+ */
+export function findMarkers(source: string): Marker[];
+/**
+ * Every link to an anchor in the document, in order, shared with later calls for the same source.
+ * @param {string} source
+ * @returns {Anchor[]}
+ */
+export function findAnchors(source: string): Anchor[];
+/**
+ * The GitHub anchor slug of a heading's rendered text.
+ * @param {string} text
+ * @returns {string}
+ */
+export function slugify(text: string): string;
+/**
+ * The text GitHub renders for a heading's inline markdown.
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function headingText(markdown: string): string;
+export const TOC_START: "<!-- toc -->";
+export const TOC_END: "<!-- /toc -->";
+/**
+ * Options written on a start marker, each `true` or a summary text, and the other attributes for the summary element.
+ */
+export type TocOptions = {
+    collapsible?: true | string;
+    collapsed?: true | string;
+    levels?: string;
+    attributes?: Record<string, string>;
+};
+/**
+ * A heading with its zero based line, level, inline markdown and GitHub slug.
+ */
+export type Headline = {
+    line: number;
+    level: number;
+    markdown: string;
+    slug: string;
+};
+/**
+ * A link to an anchor with its zero based line, text, anchor as written, whether it has a target and, when it
+ * has none and one heading clearly matches, a suggestion.
+ */
+export type Anchor = {
+    line: number;
+    text: string;
+    anchor: string;
+    valid: boolean;
+    suggestion?: string;
+};
+/**
+ * A marker pair as zero based lines, -1 for a missing side, with its options, a problem when they cannot be used and a warning when one is ignored.
+ */
+export type Marker = {
+    start: number;
+    end: number;
+    options: TocOptions;
+    problem?: string;
+    warning?: string;
+};
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1,26 +1 @@
-{
-	"version": 3,
-	"file": "index.d.ts",
-	"names": [
-		"buildToc",
-		"renderToc",
-		"findMarkers",
-		"findAnchors",
-		"slugify",
-		"headingText",
-		"TOC_START",
-		"TOC_END",
-		"TocOptions",
-		"Headline",
-		"Anchor",
-		"Marker"
-	],
-	"sources": [
-		"../index.js"
-	],
-	"sourcesContent": [
-		null
-	],
-	"mappings": ";;;;iBAcgBA,QAAQA;;;;;iBAuBRC,SAASA;;;;iBAWTC,WAAWA;;;;iBASXC,WAAWA;;;;iBASXC,OAAOA;;;;iBAYPC,WAAWA;cA9EdC,SAASA;cACTC,OAAOA;;;;aA4X0FC,UAAUA;;;;;;;;aAK1CC,QAAQA;;;;;;;;;;aAMYC,MAAMA;;;;;;;;;;aAKpBC,MAAMA",
-	"ignoreList": []
-}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,iCAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;GAMG;AACH,kCALW,MAAM,aACN,MAAM,YACN,UAAU,GACR,MAAM,CAMlB;AAED;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,EAAE,CAIpB;AAED;;;;GAIG;AACH,oCAHW,MAAM,GACJ,MAAM,EAAE,CAIpB;AAED;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAUlB;AAvFD,wBAAyB,cAAc,CAAC;AACxC,sBAAuB,eAAe,CAAC;;;;yBA6Z1B;IAAE,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE;;;;uBAKhH;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;;;;;qBAM/D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE;;;;qBAKnF;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE"}

package/index.cjs

@@ -1,410 +0,0 @@
-'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);
-/** @type {Map<string, ReturnType<typeof analyse>>} */
-const cache = new Map();
-const LINK = /\[([^\]]*)\]\(#([^)\s]+)/g;
-
-/**
- * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
- * @param {string} source
- * @returns {string}
- */
-function buildToc(source) {
-  const { bom, lines, eol, headlines, markers } = analyse(source);
-  /** @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 bom + out.join(eol);
-}
-
-/**
- * The toc block, markers included, for the headings below `fromLine`, empty when there is nothing to list.
- * @param {string} source
- * @param {number} [fromLine] zero based
- * @param {TocOptions} [options]
- * @returns {string}
- */
-function renderToc(source, fromLine = -1, options = {}) {
-  const { eol, headlines } = analyse(source);
-  const listed = headlines.filter((h) => h.line > fromLine);
-  return listed.length === 0 ? '' : renderBlock(listed, formatMarker(options), options, eol);
-}
-
-/**
- * Every marker pair in document order, shared with later calls for the same source.
- * @param {string} source
- * @returns {Marker[]}
- */
-function findMarkers(source) {
-  return analyse(source).markers;
-}
-
-/**
- * Every link to an anchor in the document, in order, shared with later calls for the same source.
- * @param {string} source
- * @returns {Anchor[]}
- */
-function findAnchors(source) {
-  return analyse(source).anchors;
-}
-
-/**
- * The GitHub anchor slug of a heading's rendered text.
- * @param {string} text
- * @returns {string}
- */
-function slugify(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\p{M} _-]/gu, '')
-    .replace(/ /g, '-');
-}
-
-/**
- * The text GitHub renders for a heading's inline markdown.
- * @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();
-}
-
-/**
- * The lines and the scan of the source.
- * @param {string} source
- * @returns {{ bom: string, lines: string[], eol: string, headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
- */
-function analyse(source) {
-  let result = cache.get(source);
-  if (!result) {
-    const { bom, lines, eol } = splitLines(source);
-    result = { bom, lines, eol, ...scan(lines) };
-    cache.clear();
-    cache.set(source, result);
-  }
-  return result;
-}
-
-/**
- * The lines of the source, its byte order mark if any, and its line ending.
- * @param {string} source
- * @returns {{ bom: string, lines: string[], eol: string }}
- */
-function splitLines(source) {
-  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
-  return { bom, lines: source.slice(bom.length).split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
-}
-
-/**
- * The headings, marker pairs and anchor links of the lines.
- * @param {string[]} lines
- * @returns {{ headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
- */
-function scan(lines) {
-  /** @type {Headline[]} */
-  const headlines = [];
-  /** @type {Marker[]} */
-  const markers = [];
-  /** @type {Array<{ line: number, text: string, anchor: string }>} */
-  const links = [];
-  /** @type {Set<string>} */
-  const ids = new Set();
-  /** @type {{ char: string, length: number } | null} */
-  let fence = null;
-  /** @type {Marker | null} */
-  let open = null;
-  let paragraph = false;
-  let comment = false;
-
-  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 };
-      paragraph = false;
-      continue;
-    }
-    if (!paragraph && /^(?: {4}|\t)/.test(line)) continue;
-    paragraph = line.trim() !== '';
-
-    const { text: inline, restore } = protect(line);
-    let visible = inline;
-    if (comment) {
-      const close = visible.indexOf('-->');
-      if (close === -1) continue;
-      visible = visible.slice(close + 3);
-      comment = false;
-    }
-    visible = visible.replace(/<!--[\s\S]*?-->/g, '');
-    const start = visible.indexOf('<!--');
-    if (start !== -1) {
-      visible = visible.slice(0, start);
-      comment = true;
-    }
-    for (const [, tag, attributes] of visible.matchAll(/<([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/g)) {
-      for (const [, name, quoted, single] of attributes.matchAll(/(?:^|\s)(id|name)=(?:"([^"]*)"|'([^']*)')/g)) {
-        if (name === 'id' || tag.toLowerCase() === 'a') ids.add(quoted ?? single);
-      }
-    }
-    for (const [, text, anchor] of visible.matchAll(LINK)) links.push({ line: i, text: restore(text), anchor: restore(anchor) });
-
-    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], slug: '' });
-      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(), slug: '' });
-    }
-  }
-  assignSlugs(headlines);
-  return { headlines, markers, anchors: resolveAnchors(links, headlines, ids) };
-}
-
-/**
- * @param {Array<{ line: number, text: string, anchor: string }>} links
- * @param {Headline[]} headlines
- * @param {Set<string>} ids
- * @returns {Anchor[]}
- */
-function resolveAnchors(links, headlines, ids) {
-  const targets = new Set([...headlines.map((h) => h.slug), ...ids]);
-  return links.map(({ line, text, anchor }) => {
-    const decoded = decodeAnchor(anchor);
-    if (targets.has(anchor) || targets.has(decoded)) return { line, text, anchor, valid: true };
-    const candidates = new Set([slugify(headingText(decoded)), slugify(headingText(text))].filter((c) => targets.has(c)));
-    if (candidates.size !== 1) return { line, text, anchor, valid: false };
-    return { line, text, anchor, valid: false, suggestion: [...candidates][0] };
-  });
-}
-
-/** @param {string} anchor */
-function decodeAnchor(anchor) {
-  try {
-    return decodeURIComponent(anchor);
-  } catch {
-    return anchor;
-  }
-}
-
-/**
- * Set the slug of every heading.
- * @param {Headline[]} headlines
- */
-function assignSlugs(headlines) {
-  /** @type {Record<string, number>} */
-  const occurrences = {};
-  for (const headline of headlines) {
-    const base = slugify(headingText(headline.markdown));
-    let slug = base;
-    while (Object.hasOwn(occurrences, slug)) {
-      occurrences[base]++;
-      slug = `${base}-${occurrences[base]}`;
-    }
-    occurrences[slug] = 0;
-    headline.slug = slug;
-  }
-}
-
-/**
- * The toc block for the headings, between the start marker line and the end marker.
- * @param {Headline[]} headlines
- * @param {string} startLine
- * @param {TocOptions} options
- * @param {string} [eol]
- */
-function renderBlock(headlines, startLine, options, eol = '\n') {
-  let minLevel = Infinity;
-  const tocLines = headlines.map(({ level, markdown, slug }) => {
-    minLevel = Math.min(minLevel, level);
-    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);
-}
-
-/**
- * The options written on a start marker, with a problem when they cannot be 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 options.
- * @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[]}
- */
-function formatAttributes(attributes) {
-  return Object.entries(attributes).map(([name, value]) => `${name}="${value}"`);
-}
-
-/**
- * The link text used in the toc for a heading.
- * @param {string} markdown
- * @returns {string}
- */
-function headingLabel(markdown) {
-  const { text, restore } = protect(stripClosingHashes(markdown), { keepCodeSpans: true });
-  return restore(stripLinks(text)).trim();
-}
-
-/**
- * The markdown with code spans and backslash escapes swapped for placeholders, and a function to put them back.
- * @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)]),
-  };
-}
-
-/**
- * The code span content unpadded as CommonMark renders it.
- * @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*$/, '');
-}
-
-/**
- * The text with links, images and autolinks flattened to their text or url.
- * @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, each `true` or a summary text, and the other attributes for the summary element.
- * @typedef {{ collapsible?: true | string, collapsed?: true | string, attributes?: Record<string, string> }} TocOptions
- */
-
-/**
- * A heading with its zero based line, level, inline markdown and GitHub slug.
- * @typedef {{ line: number, level: number, markdown: string, slug: string }} Headline
- */
-
-/**
- * A link to an anchor with its zero based line, text, anchor as written, whether it has a target and, when it
- * has none and one heading clearly matches, a suggestion.
- * @typedef {{ line: number, text: string, anchor: string, valid: boolean, suggestion?: string }} Anchor
- */
-
-/**
- * A marker pair as zero based lines, -1 for a missing side, with its options and a problem when they cannot be used.
- * @typedef {{ start: number, end: number, options: TocOptions, problem?: string }} Marker
- */
-
-exports.TOC_END = TOC_END;
-exports.TOC_START = TOC_START;
-exports.buildToc = buildToc;
-exports.findAnchors = findAnchors;
-exports.findMarkers = findMarkers;
-exports.headingText = headingText;
-exports.renderToc = renderToc;
-exports.slugify = slugify;