@datalackey/update-markdown-toc 1.0.1 → 1.0.2

package/README.md

@@ -3,6 +3,7 @@
 <!-- TOC:START -->
 - [update-markdown-toc](#update-markdown-toc)
   - [Introduction](#introduction)
+  - [Why not Some Other Markdown TOC Generator ?](#why-not-some-other-markdown-toc-generator-)
   - [Installation](#installation)
   - [Usage](#usage)
     - [Using npx (recommended)](#using-npx-recommended)
@@ -29,6 +30,18 @@ A Node.js command-line **documentation helper** which automatically:
 - avoids gratuitous reformatting or changes of any kind outside of regions marked by the aforementioned [TOC markers](#toc-markers)
 - avoids updating files when the generated TOC is already correct
 - provides a `--check` mode which flags Markdown files with stale TOCs (intended for CI)
+- generates TOC links with GitHub’s Markdown renderer.
+
+
+
+## Why not Some Other Markdown TOC Generator ?
+
+Most Markdown TOC tools (e.g., [markdown-toc](https://github.com/jonschlinkert/markdown-toc), 
+[md-toc-cli](https://github.com/eugene-khyst/md-toc-cli))
+operate on a **single file at a time**, a mode which our tool also supports.
+But we are aware of no other alternative which supports our tool's main distinguishing feature: 
+the ability to search for, check and update all Markdown documents within an entire folder hierarchy.
+
 
 
 
@@ -103,6 +116,10 @@ Options:
   -h, --help                                Show this help message and exit
 ```
 
+When using --check, a target file or a recursive folder must be specified
+explicitly. Unlike normal operation, --check does not default to README.md.
+
+
 ## TOC Markers
 
 The tool operates only on files containing **both** start and end markers,
@@ -184,7 +201,7 @@ In the case of the latter mode, we assume some files may not yet have TOC marker
 #### Single-File Processing (Strict Mode)
 
 
-When a single Markdown file is explicitly specified (or when the default README.md is used), 
+When a single Markdown file is explicitly specified (or when the default README.md is used and --check not specified), 
 the tool operates in strict mode.
 In this mode, any of the following conditions cause an immediate error and a non-zero exit code:
 

package/bin/parseCli.js

@@ -89,5 +89,9 @@ function printHelp() {
       -q, --quiet                               Suppress all non-error output
       -d, --debug                               Print debug diagnostics to stderr
       -h, --help                                Show this help message and exit
+      
+      When using --check, a target file or a recursive folder must be specified
+      explicitly. Unlike normal operation, --check does not default to README.md.
+
   `);
 }

package/bin/update-markdown-toc.js

@@ -3,6 +3,7 @@
 import fs from "fs";
 import path from "path";
 import { parseCli } from "./parseCli.js";
+import GithubSlugger from "github-slugger";
 
 /* ============================================================
  * Constants
@@ -39,6 +40,10 @@ function debugLog(msg) {
  * Helpers
  * ============================================================ */
 
+function detectLineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
 function collectMarkdownFiles(dir) {
     const results = [];
 
@@ -56,6 +61,8 @@ function collectMarkdownFiles(dir) {
 }
 
 function generateTOC(content) {
+    const lineEnding = detectLineEnding(content);
+
     const hasStart = content.includes(START);
     const hasEnd   = content.includes(END);
 
@@ -72,28 +79,27 @@ function generateTOC(content) {
     const startIndex = content.indexOf(START);
     const endIndex   = content.indexOf(END);
 
-    const before = content.slice(0, startIndex + START.length);
-    const after  = content.slice(endIndex);
+    const before = content.slice(0, startIndex);
+    const after  = content.slice(endIndex + END.length);
 
+    // Preserve exactly one line boundary for parsing
     const contentWithoutTOC =
-        content.slice(0, startIndex) +
-        content.slice(endIndex + END.length);
+        before.replace(/\s*$/, "") +
+        lineEnding +
+        after.replace(/^\s*/, "");
 
-    const lines = contentWithoutTOC.split("\n");
+    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 = title
-            .toLowerCase()
-            .replace(/[^\w\s-]/g, "")
-            .replace(/\s/g, "-")
-            .replace(/^-|-$/g, "");
+        const anchor = slugger.slug(title);
 
         headings.push({ level, title, anchor });
     }
@@ -108,10 +114,22 @@ function generateTOC(content) {
         return `${indent}- [${h.title}](#${h.anchor})`;
     });
 
-    const tocBlock = "\n" + tocLines.join("\n") + "\n";
-    return before + tocBlock + after;
+    const tocBlock =
+        lineEnding +
+        tocLines.join(lineEnding) +
+        lineEnding;
+
+    return (
+        before +
+        START +
+        tocBlock +
+        END +
+        after
+    );
 }
 
+
+
 /* ============================================================
  * File processing
  * ============================================================ */
@@ -135,7 +153,7 @@ function processFile(filePath) {
                 debugLog("result: skipped (no markers)");
                 return { status: "skipped" };
             }
-            throw err; // single-file mode → hard error
+            throw err;
         }
         throw err;
     }
@@ -165,15 +183,11 @@ function maybePrintStatus(status, filePath) {
     if (quiet) return;
 
     if (checkMode) {
-        // In --check mode we ALWAYS report stale files (unless --quiet).
-        // This makes CI output actionable without requiring --verbose.
         if (status === "stale") {
             console.log(`Stale: ${filePath}`);
             return;
         }
 
-        // In recursive mode, files without markers are intentionally ignored.
-        // They should not cause failures and do not need reporting by default.
         if (status === "skipped") {
             if (verbose) {
                 console.log(`Skipped (no markers): ${filePath}`);
@@ -207,7 +221,6 @@ function maybePrintStatus(status, filePath) {
     }
 }
 
-
 /* ============================================================
  * Execution
  * ============================================================ */
@@ -227,7 +240,7 @@ if (recursivePath) {
     }
 
     files = collectMarkdownFiles(resolved);
-    files.sort(); // deterministic order
+    files.sort();
 } else {
     const resolved = path.resolve(
         process.cwd(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,7 @@
   },
   "homepage": "https://github.com/datalackey/build-tools/tree/main/javascript/update-markdown-toc",
   "dependencies": {
+    "github-slugger": "^2.0.0",
     "ts-dedent": "^2.2.0"
   }
 }