@0dep/toc 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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`
+- `findAnchors(source)` lists every link to an anchor in the document with whether it has a target, and a suggestion when a heading obviously matches
+- the last source and its scan are cached, so the bin walks a file once instead of once per call
+- the bin checks every link to an anchor outside the regenerated pairs and warns about the ones without a target, `-c`/`--check` makes them set exit code 1
+- a byte order mark at the start of the file is ignored and kept, a heading or start marker on the first line used to be missed
+
 ## v1.0.1 - 2026-09-12
 
 - `updateToc` is removed and the library no longer imports anything from Node, so it runs in the browser too. Reading and writing files is the `toc` bin's job, use `buildToc` with your own IO

package/README.md

@@ -4,7 +4,7 @@
 
 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.
+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.
 
 <!-- toc -->
 
@@ -16,12 +16,14 @@ The toc is written between `<!-- toc -->` and `<!-- /toc -->` markers, and only
 - [CLI](#cli)
   - [Options](#options-1)
   - [Output and exit code](#output-and-exit-code)
+  - [Anchors](#anchors)
   - [Dry run](#dry-run)
   - [With prettier](#with-prettier)
 - [API](#api)
   - [`buildToc(source)`](#buildtocsource)
   - [`renderToc(source[, fromLine[, options]])`](#rendertocsource-fromline-options)
   - [`findMarkers(source)`](#findmarkerssource)
+  - [`findAnchors(source)`](#findanchorssource)
   - [`slugify(text)`](#slugifytext)
   - [`headingText(markdown)`](#headingtextmarkdown)
   - [`TOC_START` and `TOC_END`](#toc_start-and-toc_end)
@@ -71,7 +73,7 @@ becomes
 ## 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.
+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. A byte order mark is ignored, a heading or marker on the first line is still seen, and the mark is kept when the file is written.
 
 ### Several tocs in one document
 
@@ -149,7 +151,7 @@ Anything on the start marker that is not one of the two options or a well-formed
 
 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.
+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. Duplicates are counted over the whole document, headings above the start marker included, since that is what GitHub does.
 
 ## CLI
 
@@ -158,6 +160,7 @@ 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 --check README.md      # exit with 1 when a link to an anchor has no target
 npx toc --help
 ```
 
@@ -168,6 +171,7 @@ Paths are resolved against the current directory.
 | 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                                                                    |
 
 ### Output and exit code
@@ -185,9 +189,21 @@ 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: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                |
 
-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.
+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.
+
+### Anchors
+
+Every link to an anchor in the file, `[text](#slug)`, is checked against the slugs of the headings, the `id` of any html element and the `name` of an `<a>` in the file, outside fenced and indented code blocks, code spans and html comments. A bare `#`, the top of the page, and a fragment on a path or url to another document, `other.md#install`, are not anchors in this file and are left alone. Links inside a pair that is being regenerated are not checked, the new toc replaces them. A link without a target is reported with its line number, and the exit code stays 0 unless `--check` is given, so a stale link does not stop the toc from being written.
+
+The warning ends with `did you mean` when the target is obvious: slugging the anchor as written, `#My-Heading` or `#My%20Heading` for `## My Heading`, or slugging the link text, `[My Heading](#heading)`, lands on exactly one existing target. The link itself is never rewritten, nothing outside the markers is.
+
+```sh
+npx toc --check docs/*.md
+```
 
 ### Dry run
 
@@ -227,6 +243,7 @@ To regenerate the toc and format the rest of the file in one go, let a `posttoc`
 - [`buildToc(source)`](#buildtocsource)
 - [`renderToc(source[, fromLine[, options]])`](#rendertocsource-fromline-options)
 - [`findMarkers(source)`](#findmarkerssource)
+- [`findAnchors(source)`](#findanchorssource)
 - [`slugify(text)`](#slugifytext)
 - [`headingText(markdown)`](#headingtextmarkdown)
 - [`TOC_START` and `TOC_END`](#toc_start-and-toc_end)
@@ -240,7 +257,7 @@ To regenerate the toc and format the rest of the file in one go, let a `posttoc`
 <!-- /toc -->
 
 ```javascript
-import { buildToc, renderToc, findMarkers, slugify, headingText, TOC_START, TOC_END } from '@0dep/toc';
+import { buildToc, renderToc, findMarkers, findAnchors, slugify, headingText, TOC_START, TOC_END } from '@0dep/toc';
 ```
 
 CommonJS works the same way with `require('@0dep/toc')`.
@@ -308,9 +325,27 @@ console.log(findMarkers('# Title\n\n<!-- toc collapsed -->\n<!-- /toc -->\n\n##
 ]
 ```
 
+### `findAnchors(source)`
+
+Returns every link to an anchor in document order as `{ line, text, anchor, valid }`: the zero based line, the link text, the anchor without the `#` and with backslash escapes resolved, and whether the document has a heading slug, an html `id` or an `<a name>` for it. Links and targets inside fenced and indented code blocks, code spans and html comments are ignored. When there is no target and exactly one heading matches the slugged anchor or the slugged link text, `suggestion` names it, and is otherwise absent.
+
+```javascript
+import { findAnchors } from '@0dep/toc';
+
+console.log(findAnchors('## My Heading\n\n[a](#my-heading) [b](#My-Heading) [c](#nope)\n'));
+```
+
+```text
+[
+  { line: 2, text: 'a', anchor: 'my-heading', valid: true },
+  { line: 2, text: 'b', anchor: 'My-Heading', valid: false, suggestion: 'my-heading' },
+  { line: 2, text: 'c', anchor: 'nope', valid: false }
+]
+```
+
 ### `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.
+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 get `-1`, `-2` and so on, counted over the whole document, like GitHub.
 
 ```javascript
 import { slugify } from '@0dep/toc';
@@ -370,7 +405,7 @@ The link text is the heading's own markdown, so inline code and emphasis are kep
 
 ### 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.
+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. Duplicates are numbered over the whole document, headings above the markers included. See `slugify` and `headingText` above.
 
 ## License
 

package/bin/toc.js

@@ -2,7 +2,7 @@
 /* eslint-disable no-console */
 import { readFile, writeFile } from 'node:fs/promises';
 
-import { buildToc, findMarkers, renderToc } from '../index.js';
+import { buildToc, findAnchors, findMarkers, renderToc } from '../index.js';
 
 const USAGE = `Usage: toc [options] [file...]
 
@@ -10,7 +10,9 @@ 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.
+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.
 
 Markers:
   <!-- toc -->                          plain list
@@ -18,7 +20,9 @@ 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 -->                         end of the block Files are resolved against the current directory and default to
+  <!-- /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.
 
@@ -26,13 +30,14 @@ 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
   -h, --help     show this help
 `;
 
 await main();
 
 async function main() {
-  const { files, dryRun, help, unknown } = parseArgs(process.argv.slice(2));
+  const { files, help, unknown, ...flags } = parseArgs(process.argv.slice(2));
 
   if (unknown) {
     console.error(`Unknown option: ${unknown}\n\n${USAGE}`);
@@ -46,7 +51,7 @@ async function main() {
 
   for (const file of files) {
     try {
-      await processFile(file, dryRun);
+      await processFile(file, flags);
     } catch (err) {
       console.error(`${file}: ${/** @type {Error} */ (err).message}`);
       process.exitCode = 1;
@@ -55,26 +60,52 @@ async function main() {
 }
 
 /**
- * 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.
+ * Update the toc and check the anchors of one file, or report what would happen with `dryRun`.
  * @param {string} file
- * @param {boolean} dryRun
+ * @param {{ dryRun: boolean, check: boolean }} flags
  */
-async function processFile(file, dryRun) {
+async function processFile(file, { dryRun, check }) {
   const source = await readFile(file, 'utf8');
+  const status = dryRun ? console.error : console.log;
+  const warn = console.error;
+
+  const regenerated = reportMarkers(file, source, dryRun);
+  let updated = source;
+  if (regenerated.length) {
+    updated = buildToc(source);
+    if (updated === source) status(`${file}: TOC already up to date.`);
+    else status(`${file}: ${dryRun ? 'would write' : 'wrote'} TOC.`);
+  }
+
+  for (const { line, anchor, valid, suggestion } of findAnchors(source)) {
+    if (valid || regenerated.some(({ start, end }) => line >= start && line <= end)) continue;
+    if (suggestion) warn(`${file}:${line + 1}: anchor #${anchor} has no target, did you mean #${suggestion}?`);
+    else warn(`${file}:${line + 1}: anchor #${anchor} has no target.`);
+    if (check) process.exitCode = 1;
+  }
+
+  if (!dryRun && updated !== source) await writeFile(file, updated);
+}
+
+/**
+ * @param {string} file
+ * @param {string} source
+ * @param {boolean} dryRun
+ * @returns {Array<{ start: number, end: number }>}
+ */
+function reportMarkers(file, source, dryRun) {
   const markers = findMarkers(source);
   const warn = console.error;
+  /** @type {Array<{ start: number, end: number }>} */
+  const regenerated = [];
 
   if (markers.length === 0) {
     const toc = renderToc(source);
     if (dryRun && toc) console.log(toc);
     warn(`${file}: no TOC markers, skipped.`);
-    return;
+    return regenerated;
   }
 
-  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.`);
@@ -85,35 +116,25 @@ async function processFile(file, dryRun) {
     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.`);
+    else regenerated.push({ start, end });
   }
+  return regenerated;
 }
 
 /**
  * @param {string[]} argv
- * @returns {{ files: string[], dryRun: boolean, help: boolean, unknown?: string }}
+ * @returns {{ files: string[], dryRun: boolean, check: boolean, help: boolean, unknown?: string }}
  */
 function parseArgs(argv) {
   /** @type {string[]} */
   const files = [];
-  let dryRun = false;
-  let help = false;
+  const flags = { dryRun: false, check: false, 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 };
+    if (arg === '-n' || arg === '--dry-run') flags.dryRun = true;
+    else if (arg === '-c' || arg === '--check') flags.check = 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'], dryRun, help };
+  return { files: files.length ? files : ['README.md'], ...flags };
 }

package/index.cjs

@@ -5,18 +5,17 @@ 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;
 
 /**
- * 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.
+ * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
  * @param {string} source
  * @returns {string}
  */
 function buildToc(source) {
-  const { lines, eol } = splitLines(source);
-  const { headlines, markers } = scan(lines);
+  const { bom, lines, eol, headlines, markers } = analyse(source);
   /** @type {string[]} */
   const out = [];
   let cursor = 0;
@@ -28,39 +27,42 @@ function buildToc(source) {
     cursor = end + 1;
   }
   out.push(...lines.slice(cursor));
-  return out.join(eol);
+  return bom + 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.
+ * 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 line number, typically the start marker's
- * @param {TocOptions} [options] rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+ * @param {number} [fromLine] zero based
+ * @param {TocOptions} [options]
  * @returns {string}
  */
 function renderToc(source, fromLine = -1, options = {}) {
-  const { lines, eol } = splitLines(source);
-  const listed = scan(lines).headlines.filter((h) => h.line > fromLine);
+  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 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.
+ * Every marker pair in document order, shared with later calls for the same source.
  * @param {string} source
  * @returns {Marker[]}
  */
 function findMarkers(source) {
-  return scan(splitLines(source).lines).markers;
+  return analyse(source).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.
+ * 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}
  */
@@ -72,7 +74,7 @@ function slugify(text) {
 }
 
 /**
- * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+ * The text GitHub renders for a heading's inline markdown.
  * @param {string} markdown
  * @returns {string}
  */
@@ -87,33 +89,51 @@ function headingText(markdown) {
 }
 
 /**
- * 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.
+ * 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 {{ lines: string[], eol: string }}
+ * @returns {{ bom: string, lines: string[], eol: string }}
  */
 function splitLines(source) {
-  return { lines: source.split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
+  return { bom, lines: source.slice(bom.length).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.
+ * The headings, marker pairs and anchor links of the lines.
  * @param {string[]} lines
- * @returns {{ headlines: Array<{ line: number, level: number, markdown: string }>, markers: Marker[] }}
+ * @returns {{ headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
  */
 function scan(lines) {
-  /** @type {Array<{ line: number, level: number, markdown: string }>} */
+  /** @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);
@@ -125,8 +145,32 @@ function scan(lines) {
     }
     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) {
@@ -142,42 +186,75 @@ function scan(lines) {
 
     const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line);
     if (atx) {
-      headlines.push({ line: i, level: atx[1].length, markdown: atx[2] });
+      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() });
+      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim(), slug: '' });
     }
   }
-  return { headlines, markers };
+  assignSlugs(headlines);
+  return { headlines, markers, anchors: resolveAnchors(links, headlines, ids) };
 }
 
 /**
- * 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
+ * @param {Array<{ line: number, text: string, anchor: string }>} links
+ * @param {Headline[]} headlines
+ * @param {Set<string>} ids
+ * @returns {Anchor[]}
  */
-function renderBlock(headlines, startLine, options, eol = '\n') {
+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 = {};
-  let minLevel = Infinity;
-  const tocLines = headlines.map(({ level, markdown }) => {
-    minLevel = Math.min(minLevel, level);
-    const base = slugify(headingText(markdown));
+  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;
@@ -191,10 +268,7 @@ function renderBlock(headlines, startLine, options, eol = '\n') {
 }
 
 /**
- * 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.
+ * The options written on a start marker, with a problem when they cannot be used.
  * @param {string | undefined} text
  * @returns {{ options: TocOptions, problem?: string }}
  */
@@ -223,7 +297,7 @@ function parseOptions(text) {
 }
 
 /**
- * The start marker line for the given options, the inverse of `parseOptions`: options first, then attributes.
+ * The start marker line for the options.
  * @param {TocOptions} options
  */
 function formatMarker(options) {
@@ -237,15 +311,14 @@ function formatMarker(options) {
 
 /**
  * @param {Record<string, string>} attributes
- * @returns {string[]} `name="value"` in the order given
+ * @returns {string[]}
  */
 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.
+ * The link text used in the toc for a heading.
  * @param {string} markdown
  * @returns {string}
  */
@@ -255,8 +328,7 @@ function headingLabel(markdown) {
 }
 
 /**
- * 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.
+ * 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]
  */
@@ -276,8 +348,7 @@ function protect(markdown, { keepCodeSpans = false } = {}) {
 }
 
 /**
- * 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.
+ * The code span content unpadded as CommonMark renders it.
  * @param {string} code
  */
 function unpadCodeSpan(code) {
@@ -291,8 +362,7 @@ function stripClosingHashes(markdown) {
 }
 
 /**
- * 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.
+ * The text with links, images and autolinks flattened to their text or url.
  * @param {string} text
  */
 function stripLinks(text) {
@@ -310,22 +380,30 @@ function isParagraphText(line) {
 }
 
 /**
- * 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.
+ * 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 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.
+ * 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;

package/index.js

@@ -3,18 +3,17 @@ export 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;
 
 /**
- * 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.
+ * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
  * @param {string} source
  * @returns {string}
  */
 export function buildToc(source) {
-  const { lines, eol } = splitLines(source);
-  const { headlines, markers } = scan(lines);
+  const { bom, lines, eol, headlines, markers } = analyse(source);
   /** @type {string[]} */
   const out = [];
   let cursor = 0;
@@ -26,39 +25,42 @@ export function buildToc(source) {
     cursor = end + 1;
   }
   out.push(...lines.slice(cursor));
-  return out.join(eol);
+  return bom + 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.
+ * 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 line number, typically the start marker's
- * @param {TocOptions} [options] rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+ * @param {number} [fromLine] zero based
+ * @param {TocOptions} [options]
  * @returns {string}
  */
 export function renderToc(source, fromLine = -1, options = {}) {
-  const { lines, eol } = splitLines(source);
-  const listed = scan(lines).headlines.filter((h) => h.line > fromLine);
+  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 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.
+ * Every marker pair in document order, shared with later calls for the same source.
  * @param {string} source
  * @returns {Marker[]}
  */
 export function findMarkers(source) {
-  return scan(splitLines(source).lines).markers;
+  return analyse(source).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.
+ * 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) {
+  return analyse(source).anchors;
+}
+
+/**
+ * The GitHub anchor slug of a heading's rendered text.
  * @param {string} text
  * @returns {string}
  */
@@ -70,7 +72,7 @@ export function slugify(text) {
 }
 
 /**
- * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+ * The text GitHub renders for a heading's inline markdown.
  * @param {string} markdown
  * @returns {string}
  */
@@ -85,33 +87,51 @@ export function headingText(markdown) {
 }
 
 /**
- * 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.
+ * 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 {{ lines: string[], eol: string }}
+ * @returns {{ bom: string, lines: string[], eol: string }}
  */
 function splitLines(source) {
-  return { lines: source.split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
+  return { bom, lines: source.slice(bom.length).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.
+ * The headings, marker pairs and anchor links of the lines.
  * @param {string[]} lines
- * @returns {{ headlines: Array<{ line: number, level: number, markdown: string }>, markers: Marker[] }}
+ * @returns {{ headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
  */
 function scan(lines) {
-  /** @type {Array<{ line: number, level: number, markdown: string }>} */
+  /** @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);
@@ -123,8 +143,32 @@ function scan(lines) {
     }
     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) {
@@ -140,42 +184,75 @@ function scan(lines) {
 
     const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line);
     if (atx) {
-      headlines.push({ line: i, level: atx[1].length, markdown: atx[2] });
+      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() });
+      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim(), slug: '' });
     }
   }
-  return { headlines, markers };
+  assignSlugs(headlines);
+  return { headlines, markers, anchors: resolveAnchors(links, headlines, ids) };
 }
 
 /**
- * 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
+ * @param {Array<{ line: number, text: string, anchor: string }>} links
+ * @param {Headline[]} headlines
+ * @param {Set<string>} ids
+ * @returns {Anchor[]}
  */
-function renderBlock(headlines, startLine, options, eol = '\n') {
+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 = {};
-  let minLevel = Infinity;
-  const tocLines = headlines.map(({ level, markdown }) => {
-    minLevel = Math.min(minLevel, level);
-    const base = slugify(headingText(markdown));
+  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;
@@ -189,10 +266,7 @@ function renderBlock(headlines, startLine, options, eol = '\n') {
 }
 
 /**
- * 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.
+ * The options written on a start marker, with a problem when they cannot be used.
  * @param {string | undefined} text
  * @returns {{ options: TocOptions, problem?: string }}
  */
@@ -221,7 +295,7 @@ function parseOptions(text) {
 }
 
 /**
- * The start marker line for the given options, the inverse of `parseOptions`: options first, then attributes.
+ * The start marker line for the options.
  * @param {TocOptions} options
  */
 function formatMarker(options) {
@@ -235,15 +309,14 @@ function formatMarker(options) {
 
 /**
  * @param {Record<string, string>} attributes
- * @returns {string[]} `name="value"` in the order given
+ * @returns {string[]}
  */
 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.
+ * The link text used in the toc for a heading.
  * @param {string} markdown
  * @returns {string}
  */
@@ -253,8 +326,7 @@ function headingLabel(markdown) {
 }
 
 /**
- * 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.
+ * 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]
  */
@@ -274,8 +346,7 @@ function protect(markdown, { keepCodeSpans = false } = {}) {
 }
 
 /**
- * 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.
+ * The code span content unpadded as CommonMark renders it.
  * @param {string} code
  */
 function unpadCodeSpan(code) {
@@ -289,8 +360,7 @@ function stripClosingHashes(markdown) {
 }
 
 /**
- * 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.
+ * The text with links, images and autolinks flattened to their text or url.
  * @param {string} text
  */
 function stripLinks(text) {
@@ -308,15 +378,22 @@ function isParagraphText(line) {
 }
 
 /**
- * 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.
+ * 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 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.
+ * 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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0dep/toc",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Generate a GitHub flavoured markdown table of contents",
   "type": "module",
   "sideEffects": false,
@@ -25,7 +25,7 @@
     "test": "mocha",
     "posttest": "npm run lint && npm run tsc && npm run test:md",
     "test:md": "texample",
-    "toc": "node bin/toc.js README.md",
+    "toc": "node bin/toc.js --check README.md",
     "posttoc": "prettier --write README.md",
     "lint": "eslint . --cache && prettier . --check --cache",
     "tsc": "tsc -p test",

package/types/index.d.ts

@@ -1,42 +1,33 @@
 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.
+	 * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
 	 * */
 	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' }`
+	 * 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 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.
+	 * Every marker pair in document order, shared with later calls for the same source.
 	 * */
 	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.
+	 * 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;
 	/**
-	 * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+	 * 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. `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.
+	 * 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;
@@ -44,8 +35,27 @@ declare module '@0dep/toc' {
 		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.
+	 * 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;

package/types/index.d.ts.map

@@ -5,11 +5,14 @@
 		"buildToc",
 		"renderToc",
 		"findMarkers",
+		"findAnchors",
 		"slugify",
 		"headingText",
 		"TOC_START",
 		"TOC_END",
 		"TocOptions",
+		"Headline",
+		"Anchor",
 		"Marker"
 	],
 	"sources": [
@@ -18,6 +21,6 @@
 	"sourcesContent": [
 		null
 	],
-	"mappings": ";;;;;;;iBAcgBA,QAAQA;;;;;;;iBAyBRC,SAASA;;;;;;;iBAcTC,WAAWA;;;;;;iBAWXC,OAAOA;;;;iBAYPC,WAAWA;cA5EdC,SAASA;cACTC,OAAOA;;;;;;;aAyT0FC,UAAUA;;;;;;;;;aAMpCC,MAAMA",
+	"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": []
 }