@datalackey/update-markdown-toc 0.1.3 → 1.0.1

package/README.md

@@ -1,21 +1,23 @@
 # update-markdown-toc
 
+<!-- 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)
+  - [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
 
@@ -23,7 +25,8 @@ A Node.js command-line **documentation helper** which automatically:
 
 - generates Table of Contents (TOC) blocks for Markdown files
 - operates on either a single file, or recursively finds all `*.md` files from a root path
-- regenerates TOCs from headings, replacing only explicitly marked regions, with no gratuitous reformatting
+- regenerates TOCs from headings, targeting only regions explicitly marked with [TOC markers](#toc-markers)
+- 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)
 
@@ -102,24 +105,29 @@ Options:
 
 ## TOC Markers
 
-The tool operates only on files containing **both** 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 !
+
 
 ```md
-<!-- TOC:START -->
-<!-- TOC:END -->
+{!-- TOC:START --}
+{!-- TOC:END --}
 ```
 
-Any existing content between these markers is lost. The new content will be the generated TOC that
+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.
 
 
 ## Usage Scenarios 
 
 
 
-
 ### 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 
@@ -143,9 +151,9 @@ Your `package.json` might look like this:
 }
 ```
 
-### Continuous Integration  (CI)
+### Continuous Integration  
 
-The --check flag is designed primarily for continuous integration.
+The --check flag is designed primarily for continuous integration (CI).
 
 In this mode, the tool:
 
@@ -175,16 +183,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), the tool operates in strict mode.
 
-In this mode:
+When a single Markdown file is explicitly specified (or when the default README.md is used), 
+the tool operates in strict mode.
+In this mode, any of the following conditions cause an immediate error and a non-zero exit code:
 
-The file must contain both TOC markers:
-```md
-<!-- TOC:START -->
-<!-- TOC:END -->
+- 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 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.
 
-```
 
 If either marker is missing, the tool prints an error message and exits with a non-zero status code.
 
@@ -193,12 +202,19 @@ If either marker is missing, the tool prints an error message and exits with a n
 
 When operating in recursive mode, the tool traverses a directory tree and processes all *.md files it finds.
 In this mode, files without TOC markers are silently skipped, and files with TOC markers are processed normally.
+(Rational: for larger repos, it may not be feasible to add TOC markers to every Markdown file at once.)
+Stale files are reported (unless --quiet is specified) and will 
+result in a non-zero return value at the end of processing, but the 
+script will not immediately bail wiht an error -- processing continues for all files found.
 
-When combined with --verbose, skipped files are reported explicitly in this mode.
+When combined with --verbose, skipped files (Markdown files without start/end region markers) 
+are reported explicitly in this mode. For example: 
 
+```bash
 update-markdown-toc --recursive docs/ --verbose
+```
 
-Example output:
+yields example output:
 
 ```
 Skipped (no markers): docs/legacy-notes.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "0.1.3",
+  "version": "1.0.1",
   "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
   "license": "MIT",
   "type": "module",