@datalackey/update-markdown-toc 1.0.0 → 1.0.2

package/README.md

@@ -2,21 +2,22 @@
 
 <!-- TOC:START -->
 - [update-markdown-toc](#update-markdown-toc)
-    - [Introduction](#introduction)
-    - [Installation](#installation)
-    - [Usage](#usage)
-        - [Using npx (recommended)](#using-npx-recommended)
-        - [Using npm scripts](#using-npm-scripts)
-        - [Using a direct path (advanced)](#using-a-direct-path-advanced)
-    - [Options](#options)
-    - [TOC Markers](#toc-markers)
-    - [Usage Scenarios](#usage-scenarios)
-        - [As Part of code/test/debug Work Flow](#as-part-of-codetestdebug-work-flow)
-        - [Continuous Integration  (CI)](#continuous-integration--ci)
-        - [Recursively Traversing a Folder Hierarchy to Process all files vs. Single File Processing](#recursively-traversing-a-folder-hierarchy-to-process-all-files-vs-single-file-processing)
-            - [Single-File Processing (Strict Mode)](#single-file-processing-strict-mode)
-            - [Recursive Folder Traversal (Lenient Mode)](#recursive-folder-traversal-lenient-mode)
-    - [Guidelines For Project Contributors](#guidelines-for-project-contributors)
+  - [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)
+    - [Using npm scripts](#using-npm-scripts)
+    - [Using a direct path (advanced)](#using-a-direct-path-advanced)
+  - [Options](#options)
+  - [TOC Markers](#toc-markers)
+  - [Usage Scenarios](#usage-scenarios)
+    - [As Part of code/test/debug Work Flow](#as-part-of-codetestdebug-work-flow)
+    - [Continuous Integration](#continuous-integration)
+    - [Recursively Traversing a Folder Hierarchy to Process all files vs. Single File Processing](#recursively-traversing-a-folder-hierarchy-to-process-all-files-vs-single-file-processing)
+      - [Single-File Processing (Strict Mode)](#single-file-processing-strict-mode)
+      - [Recursive Folder Traversal (Lenient Mode)](#recursive-folder-traversal-lenient-mode)
+  - [Guidelines For Project Contributors](#guidelines-for-project-contributors)
 <!-- TOC:END -->
 
 ## Introduction
@@ -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,23 +201,17 @@ 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:
 
 - file does not exist, or cannot be read (e.g. due to permissions).
-- file does not contain both TOC delimiters (<!-- TOC:START --> and <!-- TOC:END -->).
+- file does not contain both TOC delimiters ({!-- TOC:START --} and {!-- TOC:END --}). 
+  (See [TOC markers](#toc-markers) section about how we describe markers in this guide.)
 - file is stale (i.e. the existing TOC differs from the generated TOC). 
--  file contains TOC delimiters but no Markdown headings are found from which a TOC can be generated.
+- file contains TOC delimiters but no Markdown headings are found from which a TOC can be generated.
 
 
-
-```md
-{!-- TOC:START --}
-{!-- TOC:END --}
-
-```
-
 If either marker is missing, the tool prints an error message and exits with a non-zero status 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.0",
+  "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"
   }
 }