@datalackey/update-markdown-toc 1.4.1 → 1.4.3

package/README.md

@@ -31,6 +31,10 @@
       - [Recursive Folder Traversal (Lenient Mode)](#recursive-folder-traversal-lenient-mode)
   - [Design Goals and Philosophy](#design-goals-and-philosophy)
   - [Packaging, Publishing, and Inter-relationship with Other Plugins](#packaging-publishing-and-inter-relationship-with-other-plugins)
+  - [Heading Extraction Behavior](#heading-extraction-behavior)
+    - [Code fences are excluded](#code-fences-are-excluded)
+    - [Only ATX-style headings are included](#only-atx-style-headings-are-included)
+    - [Inline code spans are stripped before marker detection](#inline-code-spans-are-stripped-before-marker-detection)
   - [Known Limitations](#known-limitations)
   - [Contributing and Releasing](#contributing-and-releasing)
 <!-- TOC:END -->
@@ -124,7 +128,7 @@ or another method that resolves the local `update-markdown-toc` binary.
 update-markdown-toc [options] [file]
 
 Options:
-  -c, --check     <path-to-file-or-folder>  Do not write files; exit non-zero if TOC is stale
+  -c, --check                               Do not write files; exit non-zero if TOC is stale
   -n, --no-external-link-check              Skip external HTTP/HTTPS link validation during --check
   -l, --link-timeout-ms <ms>                Per-request timeout for external link checks (default: 3000)
   -r, --recursive <path-to-folder>          Recursively process all .md files under the given folder
@@ -215,11 +219,9 @@ Your `package.json` might look like this:
     "clean": "rm -rf dist",
     "compile": "tsc -p tsconfig.json",
     "pretest": "npm run compile",
-    "test": "jest",
+    "test": "vitest run",
     "docs:toc": "update-markdown-toc --recursive docs/",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --outdir=dist",
-    "package": "npm run clean && npm run compile && npm run bundle",
-    "build": "npm run docs:toc && npm run test && npm run package"
+    "build": "npm run docs:toc && npm run test && npm run compile"
   }
 }
 ```
@@ -249,7 +251,7 @@ When running with `--check`, the tool performs three tiers of link validation in
   - external links.
 
 For full details on behavior, failure output, and performance considerations
-see [Common CLI Behavior — Check Mode](../CLI-BEHAVIOR.md#
+see [Common CLI Behavior — Check Mode](../CLI-BEHAVIOR.md#6-check-mode---check)
 
 
 To skip external link validation:
@@ -305,14 +307,14 @@ In this mode:
 Recursive mode is designed for gradual adoption across larger repositories, where not every Markdown file may yet contain TOC markers.
 Unlike single-file mode, recursive mode does **not** treat missing TOC markers as an error. This allows incremental rollout of TOC enforcement.
 
-However, structural or filesystem errors still abort the run immediately. These include:
+However, structural or filesystem errors are always reported and cause a non-zero exit. These include:
 
 - unreadable files (e.g., permission errors),
 - mismatched TOC delimiters,
 - malformed TOC marker pairs,
 - files containing TOC markers but no Markdown headings.
 
-When such errors occur, the tool prints an error message and exits non-zero without continuing further traversal.
+When such errors occur, the tool prints an error message for each affected file and continues processing the remaining files. All errors are surfaced in a single pass; the process exits non-zero once traversal is complete.
 
 When combined with `--verbose`, skipped files (Markdown files without start/end region markers) are reported explicitly. For example:
 
@@ -352,6 +354,54 @@ The versioning and release of these packages is governed by a coordinated releas
 the packages adhere to common design and architectural principles policies
 that are more completely described [here](../../README.md).
 
+## Heading Extraction Behavior
+
+### Code fences are excluded
+
+Lines inside fenced code blocks are not treated as headings. A `#` character
+that appears inside a ` ``` ` block is code, not a heading, and will not appear
+in the generated TOC.
+
+If a code fence is opened but never closed, everything from the opening fence
+to the end of the document is treated as inside the fence and excluded from
+heading extraction. No error is thrown — the headings that appear before the
+unclosed fence are still included.
+
+### Only ATX-style headings are included
+
+Only headings written with leading `#` characters (ATX style) are included in
+the TOC:
+
+```markdown
+## This is included
+```
+
+Setext-style headings — a paragraph immediately followed by `---` or `===` on
+the next line — are excluded. This avoids accidentally treating a paragraph
+followed by a horizontal rule as a heading, which is a common Markdown pattern:
+
+```markdown
+A note for users.
+---
+```
+
+The line above is a paragraph + horizontal rule, not a heading, and will not
+appear in the TOC.
+
+### Inline code spans are stripped before marker detection
+
+Before checking for `<!-- TOC:START -->` and `<!-- TOC:END -->` markers, the
+document is preprocessed to remove inline code spans. This means a marker
+written inside backticks is treated as literal text and will not trigger marker
+detection:
+
+```markdown
+Use `<!-- TOC:START -->` and `<!-- TOC:END -->` as delimiters.
+```
+
+The above line is documentation about the markers, not the markers themselves.
+Only bare (unquoted) marker strings activate the TOC region.
+
 ## Known Limitations
 
 **Fragment link validation with formatted headings**
@@ -364,6 +414,7 @@ In practice this affects only headings with inline code, bold, or italic syntax.
 Plain-text headings are unaffected. A fix to unify both paths is planned for a
 future release.
 
+
 ## Contributing and Releasing
 
 For code overview, development setup, build workflow, and release procedures (including how to

package/package.json

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

package/dist/cli/TocRunConfig.d.ts

@@ -1,2 +0,0 @@
-import type { RunConfig } from "@datalackey/tooling-core";
-export type TocRunConfig = RunConfig;

package/dist/cli/TocRunConfig.js

@@ -1 +0,0 @@
-export {};