fix(rules): multiple rule fixes and no-empty-heading allowList

- heading-title-case: skip scientific notation (e.g. 1e6), hyphen compound segment handling
- no-empty-heading: add allowList and stripNumberingForAllowList for allowed empty titles
- no-heading-like-lines: strip trailing colons from fix/insert text
- one-sentence-per-line: fix space and next-word position handling
- config: enable MD046 fenced; document one-off suppression; README title case
- tests: expand unit and fix tests for above rules

Author: cypher0n3

.markdownlint.yml

@@ -29,6 +29,12 @@ MD013:
 MD033:
   allowed_elements: ["a"]
 
+# MD046/code-block-style - enforce fenced code block style (``` or ~~~).
+# Options:
+#   style: string (default "fenced"); "fenced" = fenced code block, "indented" = indented code block
+MD046:
+  style: fenced
+
 # ascii-only: disallow non-ASCII except in configured paths; inline code (backticks) always stripped. Fixable when replacement in unicodeReplacements.
 # Options (all optional):
 #   allowedEmoji: list of chars/emoji allowed in paths matching allowedPathPatternsEmoji (multi-codepoint OK)

README.md

@@ -1,4 +1,4 @@
-# Docs-as-Code Tools
+# Docs-As-Code Tools
 
 [![CI](https://github.com/cypher0n3/docs-as-code-tools/actions/workflows/js-lint.yml/badge.svg?branch=main)](https://github.com/cypher0n3/docs-as-code-tools/actions/workflows/js-lint.yml)
 [![Lint READMEs](https://github.com/cypher0n3/docs-as-code-tools/actions/workflows/lint-readmes.yml/badge.svg?branch=main)](https://github.com/cypher0n3/docs-as-code-tools/actions/workflows/lint-readmes.yml)

markdownlint-rules/.markdownlint.clean.yml

@@ -17,6 +17,28 @@
 # because allowing <a> is required for custom anchor ids. All options are
 # commented; uncomment a rule block and the options you need to override.
 #
+# -----------------------------------------------------------------------------
+# One-off suppression (allow a single line or section to bypass a rule)
+# -----------------------------------------------------------------------------
+# Custom rules support an HTML comment to suppress the rule for one line:
+#   • Put "<!-- rule-name allow -->" on the previous line (its own line), or
+#   • Put "<!-- rule-name allow -->" at the end of the violating line.
+# Examples:
+#   <!-- no-empty-heading allow -->
+#   ## Intentionally Empty
+#
+#   ## Another Empty <!-- no-empty-heading allow -->
+#
+#   <!-- heading-min-words allow -->
+#   ## Overview
+#
+#   First. Second. <!-- one-sentence-per-line allow -->
+#
+#   <!-- ascii-only allow -->
+#   Use arrow → here.
+#
+# Use the exact rule id (e.g. no-empty-heading, heading-min-words, one-sentence-per-line).
+#
 # =============================================================================
 
 default: true
@@ -254,13 +276,17 @@ default: true
 # -----------------------------------------------------------------------------
 # no-empty-heading (custom)
 # -----------------------------------------------------------------------------
-# To override: Uncomment the block and set minimumContentLines, count* options, and/or excludePathPatterns. H2+ must have content before any subheading. Per-section suppress: "<!-- no-empty-heading allow -->".
+# To override: Uncomment the block and set minimumContentLines, count* options,
+# allowList, and/or excludePathPatterns. H2+ must have content before any subheading.
+# One-off: put "<!-- no-empty-heading allow -->" on the previous line or at end of heading line.
 # Options (all optional):
 #   minimumContentLines: number (default 1); minimum lines that count as content under each H2+
 #   countBlankLinesAsContent: bool (default false); count blank lines toward minimum
 #   countHTMLCommentsAsContent: bool (default false); count HTML-comment-only lines
 #   countHtmlLinesAsContent: bool (default false); count HTML-tag-only lines (e.g. <br>)
 #   countCodeBlockLinesAsContent: bool (default true); count lines inside ```/~~~ blocks
+#   allowList: list of exact heading titles (after optional numbering strip) that may be empty
+#   stripNumberingForAllowList: bool (default true); strip leading numbering before allowList match
 #   excludePathPatterns: list of globs; skip this rule for matching file paths
 # ---
 # no-empty-heading:
@@ -269,6 +295,10 @@ default: true
 #   # countHTMLCommentsAsContent: false
 #   # countHtmlLinesAsContent: false
 #   # countCodeBlockLinesAsContent: true
+#   # allowList:
+#   #   - "Overview"
+#   #   - "Summary"
+#   # stripNumberingForAllowList: true
 #   # excludePathPatterns:
 #   #   - "**/*_index.md"
 

markdownlint-rules/README.md

@@ -287,6 +287,10 @@ no-empty-heading:
   countHTMLCommentsAsContent: false # optional; default false
   countHtmlLinesAsContent: false    # optional; default false
   countCodeBlockLinesAsContent: true # optional; default true
+  allowList:                        # optional; headings with these titles may be empty
+    - "Overview"
+    - "Summary"
+  stripNumberingForAllowList: true  # optional; default true; strip numbering before allowList match
   excludePathPatterns:
     - "**/*_index.md"               # optional; skip rule for these paths
 ```
@@ -299,13 +303,18 @@ no-empty-heading:
 - **`countHtmlLinesAsContent`** (boolean, default `false`): If `true`, lines that are only an HTML tag (e.g. `<br>`, `<div>...</div>`) count toward the minimum.
 - **`countCodeBlockLinesAsContent`** (boolean, default `true`): If `false`, lines inside fenced code blocks (` ``` `or `~~~`) do not count toward the minimum.
   When `true`, they do (default).
+- **`allowList`** (array of strings, optional): Exact heading titles (after optional numbering strip) that are allowed to have no direct content.
+  Match is case-insensitive and trimmed.
+  Same idea as `heading-min-words` allowList.
+- **`stripNumberingForAllowList`** (boolean, default `true`): When `true`, leading numbering (e.g. `1.2.3`) is stripped from the heading text before comparing to `allowList`.
 - **`excludePathPatterns`** (list of strings, default none): Glob patterns for file paths where this rule is skipped.
 
 Behavior:
 
 - For each H2-H6 heading, only _direct_ content counts: lines that appear **before** the next heading (any level).
   Content under subheadings does **not** count for the parent heading.
   Which line types count is controlled by the options above (by default: prose and code block lines; blank, HTML-comment, and HTML-tag lines do not).
+- **Allow by title:** If `allowList` is set, any H2+ heading whose title (after optional numbering strip) matches an entry (case-insensitive) is allowed to be empty.
 - **Suppress per section:** A section is allowed without meeting the minimum if it contains a line that is solely the comment `<!-- no-empty-heading allow -->` (optional whitespace around or inside the comment).
   The comment must be on its own line.
     No other HTML comment format suppresses the rule.

markdownlint-rules/heading-title-case.js

@@ -14,6 +14,9 @@ const RE_FILE_LIKE = /^[^\s`]*[A-Za-z][^\s`]*\.[A-Za-z0-9]+$/;
 /** Match HTML/XML entity (e.g. ⇒ … →) so we skip title-case checks (ASCII-safe special chars). */
 const RE_HTML_ENTITY = /^[^A-Za-z0-9]*&(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-fA-F]+);[^A-Za-z0-9]*$/;
 
+/** Scientific notation (e.g. 5e, 1e6, 2.5e-10); skip so "e" is not flagged for capitalization. */
+const RE_SCIENTIFIC = /^\d+(?:\.\d+)?[eE][+-]?\d*$/;
+
 /** Placeholder sentinels for inline code in applyTitleCase (private-use Unicode, not control chars). */
 const PLACEHOLDER_START = "\uE000";
 const PLACEHOLDER_END = "\uE001";
@@ -88,13 +91,13 @@ function isAllLower(w) {
 }
 
 /**
- * True if this position is exempt from lowercase (first/last/subphrase start/hyphen compound start/single-letter label).
- * @param {{ isFirst: boolean, isLast: boolean, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
+ * True if this position is exempt from lowercase (first/last/subphrase start/hyphen compound segment/single-letter label).
+ * @param {{ isFirst: boolean, isLast: boolean, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isHyphenCompoundSegment?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {boolean}
  */
 function isExemptFromLowercase(opts) {
-  const { isFirst, isLast, isSubphraseStart, isHyphenCompoundStart, isPhaseLabel } = opts;
-  return Boolean(isFirst || isLast || isSubphraseStart || isHyphenCompoundStart || isPhaseLabel);
+  const { isFirst, isLast, isSubphraseStart, isHyphenCompoundStart, isHyphenCompoundSegment, isPhaseLabel } = opts;
+  return Boolean(isFirst || isLast || isSubphraseStart || isHyphenCompoundStart || isHyphenCompoundSegment || isPhaseLabel);
 }
 
 /**
@@ -111,7 +114,7 @@ function getCapitalizationKind(opts) {
 
 /**
  * Validate one word for title case; returns error detail string or null if valid.
- * @param {{ raw: string, core: string, isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
+ * @param {{ raw: string, core: string, isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isHyphenCompoundSegment?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {string|null}
  */
 function checkWord(opts) {
@@ -129,7 +132,7 @@ function checkWord(opts) {
  * Return the corrected segment text for fixInfo: lowercase or capitalize per AP rules, preserving punctuation.
  * @param {string} rawSeg - Segment as in source (e.g. "And", "(in", "practice)")
  * @param {string} core - stripWordPunctuation(rawSeg)
- * @param {{ isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
+ * @param {{ isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isHyphenCompoundSegment?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {string}
  */
 function getCorrectedSegment(rawSeg, core, opts) {
@@ -169,6 +172,13 @@ function isPhaseLabelSegment(j, core, previousWordCore) {
   return j === 0 && core.length === 1 && /^[A-Za-z]$/.test(core) && LABEL_PARENT_WORDS.has(previousWordCore);
 }
 
+/** True if this segment should be skipped for title-case (entity, empty, non-alpha, or scientific notation). */
+function shouldSkipSegmentForTitleCase(rawSeg, core) {
+  return isHtmlEntity(rawSeg)
+    || !core || !/[a-zA-Z]/.test(core)
+    || RE_SCIENTIFIC.test(core);
+}
+
 /**
  * Check one segment of a word for title-case; returns error result or null.
  * @param {{ words: string[], rawSegments: string[], i: number, j: number, wordIsSubphraseStart: boolean, lowercaseWords: Set<string>, previousWordCore?: string }} opts
@@ -177,14 +187,14 @@ function isPhaseLabelSegment(j, core, previousWordCore) {
 function checkOneSegment(opts) {
   const { words, rawSegments, i, j, wordIsSubphraseStart, lowercaseWords, previousWordCore } = opts;
   const rawSeg = rawSegments[j];
-  if (isHtmlEntity(rawSeg)) return null;
   const core = stripWordPunctuation(rawSeg);
-  if (!core || !/[a-zA-Z]/.test(core)) return null;
+  if (shouldSkipSegmentForTitleCase(rawSeg, core)) return null;
 
   const isFirst = i === 0 && j === 0;
   const isLast = i === words.length - 1 && j === rawSegments.length - 1;
   const isSubphraseStart = j === 0 && wordIsSubphraseStart;
   const isHyphenCompoundStart = rawSegments.length > 1 && j === 0;
+  const isHyphenCompoundSegment = rawSegments.length > 1;
   const isPhaseLabel = isPhaseLabelSegment(j, core, previousWordCore);
 
   const detail = checkWord({
@@ -195,6 +205,7 @@ function checkOneSegment(opts) {
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isHyphenCompoundSegment,
     isPhaseLabel,
   });
   if (!detail) return null;
@@ -205,6 +216,7 @@ function checkOneSegment(opts) {
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isHyphenCompoundSegment,
     isPhaseLabel,
   });
   const seg = getSegmentPosition(rawSegments, j);
@@ -289,13 +301,15 @@ function correctSegmentForTitleCase(rawSeg, core, ctx) {
   const isLast = i === words.length - 1 && j === rawSegments.length - 1;
   const isSubphraseStart = j === 0 && wordIsSubphraseStart;
   const isHyphenCompoundStart = rawSegments.length > 1 && j === 0;
+  const isHyphenCompoundSegment = rawSegments.length > 1;
   const isPhaseLabel = isPhaseLabelSegment(j, core, previousWordCore);
   return getCorrectedSegment(rawSeg, core, {
     isFirst,
     isLast,
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isHyphenCompoundSegment,
     isPhaseLabel,
   });
 }
@@ -318,12 +332,8 @@ function processWordForTitleCase(raw, i, words, lowercaseWords) {
   const segmentParts = [];
   for (let j = 0; j < rawSegments.length; j++) {
     const rawSeg = rawSegments[j];
-    if (isHtmlEntity(rawSeg)) {
-      segmentParts.push(rawSeg);
-      continue;
-    }
     const core = stripWordPunctuation(rawSeg);
-    if (!core || !/[a-zA-Z]/.test(core)) {
+    if (shouldSkipSegmentForTitleCase(rawSeg, core)) {
       segmentParts.push(rawSeg);
       continue;
     }

markdownlint-rules/no-empty-heading.js

@@ -1,6 +1,11 @@
 "use strict";
 
-const { extractHeadings, isRuleSuppressedByComment, pathMatchesAny } = require("./utils.js");
+const {
+  extractHeadings,
+  isRuleSuppressedByComment,
+  parseHeadingNumberPrefix,
+  pathMatchesAny,
+} = require("./utils.js");
 
 /** Match HTML comment line (single line). */
 const RE_HTML_COMMENT = /^\s*<!--.*-->\s*$/;
@@ -169,10 +174,36 @@ function sectionContentLineCount(ctx) {
   return count;
 }
 
+/**
+ * Get heading title for allowList match: raw text, optionally with leading numbering stripped.
+ * @param {string} rawText - Full heading text after #
+ * @param {boolean} stripNumbering - Whether to strip leading numbering (e.g. 1.2.3)
+ * @returns {string}
+ */
+function getTitleForAllowList(rawText, stripNumbering) {
+  if (stripNumbering) {
+    const { titleText } = parseHeadingNumberPrefix(rawText);
+    return titleText;
+  }
+  return rawText.trim();
+}
+
+/**
+ * Return true if the heading title is in the allowList (case-insensitive, trimmed).
+ * @param {string} title - Heading title (from getTitleForAllowList)
+ * @param {string[]} allowList - Allowed titles
+ * @returns {boolean}
+ */
+function isAllowedEmptyHeading(title, allowList) {
+  if (!Array.isArray(allowList) || allowList.length === 0) return false;
+  const key = title.trim().toLowerCase();
+  return allowList.some((a) => String(a).trim().toLowerCase() === key);
+}
+
 /**
  * Normalize rule config to validated values.
  * @param {object} config - Raw config
- * @returns {{ minimumContentLines: number, contentOpts: { countBlankLinesAsContent: boolean, countHTMLCommentsAsContent: boolean, countHtmlLinesAsContent: boolean, countCodeBlockLinesAsContent: boolean } }}
+ * @returns {{ minimumContentLines: number, contentOpts: object, allowList: string[], stripNumberingForAllowList: boolean }}
  */
 function normalizeConfig(config) {
   const minimumContentLines = typeof config.minimumContentLines === "number" && config.minimumContentLines >= 1
@@ -190,6 +221,8 @@ function normalizeConfig(config) {
   const countCodeBlockLinesAsContent = typeof config.countCodeBlockLinesAsContent === "boolean"
     ? config.countCodeBlockLinesAsContent
     : DEFAULT_CONFIG.countCodeBlockLinesAsContent;
+  const allowList = Array.isArray(config.allowList) ? config.allowList.map(String) : [];
+  const stripNumberingForAllowList = config.stripNumberingForAllowList !== false;
   return {
     minimumContentLines,
     contentOpts: {
@@ -198,6 +231,8 @@ function normalizeConfig(config) {
       countHtmlLinesAsContent,
       countCodeBlockLinesAsContent,
     },
+    allowList,
+    stripNumberingForAllowList,
   };
 }
 
@@ -263,7 +298,16 @@ function headingHasTooLittleContent(ctx) {
 }
 
 function reportEmptyHeading(heading, ctx) {
-  const { headings, lines, headingLineNumbers, minimumContentLines, contentOpts, onError } = ctx;
+  const {
+    headings, lines, headingLineNumbers, minimumContentLines, contentOpts,
+    allowList, stripNumberingForAllowList, onError,
+  } = ctx;
+  if (isAllowedEmptyHeading(
+    getTitleForAllowList(heading.rawText, stripNumberingForAllowList),
+    allowList
+  )) {
+    return;
+  }
   if (!headingHasTooLittleContent({
     heading, headings, lines, headingLineNumbers, minimumContentLines, contentOpts,
   })) {
@@ -280,8 +324,10 @@ function reportEmptyHeading(heading, ctx) {
 /**
  * markdownlint rule: every H2+ heading must have at least one line of content
  * directly under it (before any subheading). Content under subheadings does not
- * count. Blank lines and HTML-comment-only lines do not count as content. The
- * exact comment "<!-- no-empty-heading allow -->" on its own line suppresses the error.
+ * count. Blank lines and HTML-comment-only lines do not count as content.
+ * Optional allowList: headings whose title (after optional numbering strip) matches
+ * an entry are allowed to be empty. The exact comment "<!-- no-empty-heading allow -->"
+ * on its own line suppresses the error for that section.
  *
  * @param {object} params - markdownlint params (lines, name, config)
  * @param {function(object): void} onError - Callback to report an error
@@ -295,11 +341,14 @@ function ruleFunction(params, onError) {
     return;
   }
 
-  const { minimumContentLines, contentOpts } = normalizeConfig(block);
+  const { minimumContentLines, contentOpts, allowList, stripNumberingForAllowList } = normalizeConfig(block);
   const headings = extractHeadings(lines);
   const h2Plus = headings.filter((h) => h.level >= 2);
   const headingLineNumbers = new Set(headings.map((h) => h.lineNumber));
-  const ctx = { headings, lines, headingLineNumbers, minimumContentLines, contentOpts, onError };
+  const ctx = {
+    headings, lines, headingLineNumbers, minimumContentLines, contentOpts,
+    allowList, stripNumberingForAllowList, onError,
+  };
 
   for (const heading of h2Plus) {
     reportEmptyHeading(heading, ctx);

markdownlint-rules/no-heading-like-lines.js

@@ -160,11 +160,12 @@ function findHeadingLikeMatch(trimmedLine, punctuationMarks) {
 function reportHeadingLikeError(line, index, match, ctx) {
   const { lines, headings, config, ruleConfig, convertToHeading, onError } = ctx;
   const { description, extractedTitle } = match;
+  const titleForFix = extractedTitle.replace(/:+$/, "").trim();
   const lineNumber = index + 1;
   const insertText = !convertToHeading
-    ? extractedTitle
+    ? titleForFix
     : buildConvertToHeadingInsertText({
-      lines, index, lineNumber, headings, config, ruleConfig, extractedTitle,
+      lines, index, lineNumber, headings, config, ruleConfig, extractedTitle: titleForFix,
     });
   if (isRuleSuppressedByComment(lines, lineNumber, "no-heading-like-lines")) return;
   onError({

markdownlint-rules/one-sentence-per-line.js

@@ -163,11 +163,24 @@ function spaceStartAndNextWordPos(scanned, spaceStart) {
   while (pos < scanned.length && scanned[pos] === " ") {
     pos++;
   }
-  const j = pos;
-  if (j >= scanned.length || scanned[j] === "\n" || !/[a-zA-Z0-9]/.test(scanned[j])) return null;
+  const j = nextWordPosAfterEmphasis(scanned, pos);
+  if (j === null) return null;
   return { spaceStart, j };
 }
 
+/** After position start, skip * and _, then ' and ", then return position of first [a-zA-Z0-9] or null. */
+function nextWordPosAfterEmphasis(scanned, start) {
+  let pos = start;
+  while (pos < scanned.length && (scanned[pos] === "*" || scanned[pos] === "_")) {
+    pos++;
+  }
+  while (pos < scanned.length && (scanned[pos] === "'" || scanned[pos] === '"')) {
+    pos++;
+  }
+  if (pos >= scanned.length || scanned[pos] === "\n" || !/[a-zA-Z0-9]/.test(scanned[pos])) return null;
+  return pos;
+}
+
 /**
  * Find index of the first sentence boundary (space before second sentence) in content.
  * Uses stripInlineCode; skips link/paren context; avoids decimals and abbreviations.

md_test_files/expected_errors.yml

@@ -293,6 +293,9 @@ negative_one_sentence_per_line.md:
     - line: 20
       rule: one-sentence-per-line
       message_contains: one sentence per line
+    - line: 22
+      rule: one-sentence-per-line
+      message_contains: one sentence per line
 
 negative_no_tables.md:
   errors: