@datalackey/update-markdown-toc 1.0.2 → 1.1.1

package/README.md

@@ -1,5 +1,14 @@
 # update-markdown-toc
 
+<p align="center">
+  <img
+    src="doc/demo.gif"
+    width="720"
+    alt="update-markdown-toc demo">
+</p>
+
+
+
 <!-- TOC:START -->
 - [update-markdown-toc](#update-markdown-toc)
   - [Introduction](#introduction)
@@ -36,12 +45,11 @@ A Node.js command-line **documentation helper** which automatically:
 
 ## Why not Some Other Markdown TOC Generator ?
 
-Most Markdown TOC tools (e.g., [markdown-toc](https://github.com/jonschlinkert/markdown-toc), 
+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.
-
+operate on a single file at a time, a mode which we also support.
+The primary distinguishing feature of our tool is its ability to recursively search for, check, and update all Markdown documents within an entire folder hierarchy, making it suitable for CI and 
+large repositories.
 
 
 
@@ -123,20 +131,17 @@ 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,
-as *almost* shown below.  Don't use these markers exactly as written. Use brackets ('<' and '>'), and not
-squiggley braces   (i.e., not '{' and '}').  The reason for this documentation 
-oddity is that, if we used brackets,
-then when we run our tool against this code base we would end up getting an unwanted table of contents below !
+as shown below:  
+
+
+&nbsp;&nbsp;&nbsp;   &lt;!-- TOC:START --&gt;<br/>
+&nbsp;&nbsp;&nbsp;   &lt;!-- TOC:END --&gt;
 
 
-```md
-{!-- TOC:START --}
-{!-- TOC:END --}
-```
 
 Any existing content between the region start and end markers is lost. The new content will be the generated TOC that
 reflects the section headers marked with '#'s in the Markdown document.
- 
+
 Content outside the markers is preserved verbatim.
 If either marker is missing, the tool prints an error message and exits with a non-zero status code.
 
@@ -148,7 +153,7 @@ If either marker is missing, the tool prints an error message and exits with a n
 ### As Part of code/test/debug Work Flow  
 
 To ensure that your code is built afresh, passes tests, and that your documentation TOCs are up to date, you could 
-use invoke the tool in something akin to the package.json below. 
+invoke the tool via something akin to the package.json below. 
 Before commit and push, you would type:  'npm run build' 
 
 
@@ -206,8 +211,7 @@ 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 --}). 
-  (See [TOC markers](#toc-markers) section about how we describe markers in this guide.)
+- file does not contain both TOC delimiters (&lt;!-- TOC:START --&gt;  and &nbsp; &lt;!-- TOC:END --&gt;).
 - 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.
 
@@ -239,6 +243,23 @@ Updated: docs/guide.md
 Up-to-date: docs/api.md
 ```
 
+## Design Goals and Philosophy
+
+This tool was designed in accordance with the top-level
+[Build Philosophy](../../README.md#build-philosophy) of this repository.
+
+
+- **update mode** (writes files: this should be run locally by developers, and should never run in CI)
+- **check mode** (validates and exits non-zero if stale:  mainly intended to be run in CI -- optional for local use) 
+
+The intended workflow is:
+
+1. Developers run the update command locally.
+2. Generated TOC content is reviewed and committed.
+3. CI runs in `--check` mode to ensure no drift exists.
+
+
 ## Guidelines For Project Contributors
 
 Contributors to the project should consult [this document](GUIDELINES-FOR-PROJECT-CONTRIBUTORS.md)
+

package/bin/update-markdown-toc.js

@@ -128,8 +128,6 @@ function generateTOC(content) {
     );
 }
 
-
-
 /* ============================================================
  * File processing
  * ============================================================ */
@@ -141,7 +139,8 @@ function processFile(filePath) {
     try {
         content = fs.readFileSync(filePath, "utf8");
     } catch {
-        throw new Error(`Unable to read markdown file: ${filePath}`);
+        const absolutePath = path.resolve(filePath);
+        throw new Error(`Unable to read markdown file: ${absolutePath}`);
     }
 
     let updated;
@@ -153,9 +152,10 @@ function processFile(filePath) {
                 debugLog("result: skipped (no markers)");
                 return { status: "skipped" };
             }
-            throw err;
         }
-        throw err;
+
+        const absolutePath = path.resolve(filePath);
+        throw new Error(`${absolutePath}: ${err.message}`);
     }
 
     if (updated === content) {

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "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": {
+    "test": "bash scripts/run-all-tests.sh"
+  },
   "bin": {
     "update-markdown-toc": "./bin/update-markdown-toc.js"
   },
@@ -17,6 +21,7 @@
     "build",
     "automation",
     "javascript",
+    "typescript",
     "node",
     "documentation",
     "readme",