@datalackey/update-markdown-toc 1.2.1 → 1.4.0

package/README.md

@@ -316,11 +316,6 @@ When such errors occur, the tool prints an error message and exits non-zero with
 
 When combined with `--verbose`, skipped files (Markdown files without start/end region markers) are reported explicitly. For example:
 
-```bash
-update-markdown-toc --recursive docs/ --verbose
-
-
-
 ```bash
 update-markdown-toc --recursive docs/ --verbose
 ```
@@ -371,7 +366,8 @@ future release.
 
 ## Contributing and Releasing
 
-For development setup, build workflow, and release procedures (including how to
+For code overview, development setup, build workflow, and release procedures (including how to
 trigger a publish via Changesets), see
-[CONTRIBUTING.md](../docs/CONTRIBUTING.md).
+[CONTRIBUTING.md](./docs/CONTRIBUTING.md).
+
 

package/dist/cli/descriptor.d.ts

@@ -1,3 +1,2 @@
 import type { PluginDescriptor } from "@datalackey/tooling-core";
-import type { TocRunConfig } from "./TocRunConfig.js";
-export declare const descriptor: PluginDescriptor<TocRunConfig>;
+export declare const descriptor: PluginDescriptor;

package/dist/cli/descriptor.js

@@ -1,50 +1,12 @@
-import { parseBooleanOption, parseNumberOption, runLinkValidation, } from "@datalackey/tooling-core";
-const DEFAULT_LINK_TIMEOUT_MS = 3000;
+import { runLinkValidation } from "@datalackey/tooling-core";
 export const descriptor = {
     name: "update-markdown-toc",
     description: "Auto-generate Table of Contents for Markdown files",
-    options: [
-        {
-            flag: "--no-external-link-check",
-            description: "Skip external link validation in check mode",
-        },
-        {
-            flag: "-n",
-            description: "Skip external link validation in check mode (short form)",
-        },
-        {
-            flag: "--link-timeout-ms",
-            description: "Timeout in milliseconds for external link requests (default: 3000)",
-            requiresValue: true,
-            valueName: "ms",
-        },
-        {
-            flag: "-l",
-            description: "Timeout in milliseconds for external link requests (short form)",
-            requiresValue: true,
-            valueName: "ms",
-        },
-    ],
-    parseOptions(standard, passthrough) {
-        const noExternalCheck = parseBooleanOption("--no-external-link-check", passthrough) ||
-            parseBooleanOption("-n", passthrough);
-        const timeoutMs = parseNumberOption("--link-timeout-ms", passthrough) ??
-            parseNumberOption("-l", passthrough) ??
-            DEFAULT_LINK_TIMEOUT_MS;
-        return {
-            ...standard,
-            validateExternalLinks: noExternalCheck ? false : true,
-            linkTimeoutMs: timeoutMs,
-        };
-    },
+    options: [],
     async afterRun(files, config) {
         if (config.runMode !== "check") {
             return;
         }
-        await runLinkValidation(files, {
-            ...config,
-            validateExternalLinks: config.validateExternalLinks,
-            linkTimeoutMs: config.linkTimeoutMs,
-        });
+        await runLinkValidation(files, config);
     },
 };

package/dist/engine/generateToc.d.ts

@@ -1 +1,2 @@
+export declare function stripInlineCode(text: string): string;
 export declare function generateTOC(content: string): string;

package/dist/engine/generateToc.js

@@ -1,13 +1,19 @@
-import GithubSlugger from "github-slugger";
+import { parseHeadings } from "@datalackey/tooling-core";
 const START = "<!-- TOC:START -->";
 const END = "<!-- TOC:END -->";
+export function stripInlineCode(text) {
+    // [^`\n]* — any char except backtick or newline (inline spans can't cross lines)
+    // Replace with "" not "``" — substituting backticks reintroduces spans that eat surrounding text
+    return text.replace(/`[^`\n]*`/g, "");
+}
 function detectLineEnding(text) {
     return text.includes("\r\n") ? "\r\n" : "\n";
 }
 export function generateTOC(content) {
     const lineEnding = detectLineEnding(content);
-    const hasStart = content.includes(START);
-    const hasEnd = content.includes(END);
+    const stripped = stripInlineCode(content);
+    const hasStart = stripped.includes(START);
+    const hasEnd = stripped.includes(END);
     if (!hasStart && !hasEnd)
         throw new Error("TOC delimiters not found");
     if (hasStart && !hasEnd)
@@ -18,26 +24,29 @@ export function generateTOC(content) {
     const endIndex = content.indexOf(END);
     const before = content.slice(0, startIndex);
     const after = content.slice(endIndex + END.length);
-    const contentWithoutTOC = before.replace(/\s*$/, "") + lineEnding + after.replace(/^\s*/, "");
-    const lines = contentWithoutTOC.split(lineEnding);
-    const headings = [];
-    const slugger = new GithubSlugger();
-    for (const line of lines) {
-        const m = /^(#{1,6})\s+(.*)$/.exec(line);
-        if (!m)
-            continue;
-        const level = m[1].length;
-        const title = m[2].trim();
-        const anchor = slugger.slug(title);
-        headings.push({ level: level, title: title, anchor: anchor });
-    }
+    // Two line endings (a blank line) are required between before and after so
+    // that any open HTML block in `before` (e.g. a closing </p> tag with no
+    // trailing blank line) is closed before remark parses `after`. A single \n
+    // is not enough — CommonMark only closes an HTML block at a blank line.
+    const contentWithoutTOC = before.replace(/\s*$/, "") +
+        lineEnding +
+        lineEnding +
+        after.replace(/^\s*/, "");
+    // parseHeadings (remark/CommonMark) also returns setext-style headings — text
+    // immediately followed by `---` or `===` on the next line. This is valid
+    // CommonMark but users writing `paragraph\n---` as a paragraph + horizontal
+    // rule (a very common pattern) will unintentionally produce TOC entries.
+    // We restrict to ATX-style headings (lines starting with `#`) which are the
+    // only form a user would deliberately put in a TOC.
+    const sourceLines = contentWithoutTOC.split(lineEnding);
+    const headings = parseHeadings(contentWithoutTOC).filter((h) => h.line > 0 && /^#{1,6}\s/.test(sourceLines[h.line - 1] ?? ""));
     if (headings.length === 0) {
         throw new Error("No headings found to generate TOC");
     }
     const minLevel = Math.min(...headings.map((h) => h.level));
     const tocLines = headings.map((h) => {
         const indent = "  ".repeat(h.level - minLevel);
-        return `${indent}- [${h.title}](#${h.anchor})`;
+        return `${indent}- [${h.rawText}](#${h.slug})`;
     });
     const tocBlock = lineEnding + tocLines.join(lineEnding) + lineEnding;
     return before + START + tocBlock + END + after;

package/dist/engine/processFile.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { generateTOC } from "./generateToc.js";
-import { debugLog } from "@datalackey/tooling-core";
+import { debugLog, toErrorMessage } from "@datalackey/tooling-core";
 export function processFile(filePath, config) {
     const absolutePath = path.resolve(filePath);
     debugLog(config, `processFile: entry filePath=${absolutePath} runMode=${config.runMode}`);
@@ -17,7 +17,7 @@ export function processFile(filePath, config) {
         updated = generateTOC(content);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = toErrorMessage(err);
         if (message === "TOC delimiters not found" && config.mode === "recursive") {
             debugLog(config, `processFile: skipped (no markers) filePath=${absolutePath}`);
             return "skipped";

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
   "license": "MIT",
   "type": "module",
   "private": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npx vitest run --config vitest.config.ts && bash scripts/run-all-tests.sh"
+    "prepack": "npx nx build @datalackey/update-markdown-toc 1>&2"
   },
   "bin": {
     "update-markdown-toc": "./bin/update-markdown-toc.js"