fix(markdownlint-rules): matchGlob cwd-aware globs and suppress across blank lines

matchGlob no longer treats bare filenames as **/name; match project-root paths
via cwd-relative single segments (and limited ../), path.normalize, and
absolute paths from the CLI. isRuleSuppressedByComment scans past blank lines
to find HTML allow comments. Add no-h1-content fixtures and tests, doc updates,
and drop stale no-empty-heading expectation for wrong-format suppress.

Author: cypher0n3

markdownlint-rules/.markdownlint.clean.yml

@@ -23,7 +23,7 @@
 # Custom rules support HTML comments to suppress the rule:
 #
 # One-off (single line):
-#   • Put "<!-- rule-name allow -->" on the previous line (its own line), or
+#   • Put "<!-- rule-name allow -->" on its own line before the line to suppress (blank lines in between are OK), or
 #   • Put "<!-- rule-name allow -->" at the end of the violating line.
 #
 # Block (disable then enable):

markdownlint-rules/README.md

@@ -36,7 +36,7 @@ Some rules are **fixable** (heading-title-case, ascii-only, heading-numbering, n
   Only rules that accept options are documented with a config section below.
   **Regex patterns in YAML:** use single quotes so backslashes are not interpreted by YAML (e.g. `'\s'` instead of `"\\s"`), avoiding unnecessary double escapes.
 - **Suppressing a rule:** Every custom rule supports HTML comment overrides.
-  - **One-off:** Put `<!-- rule-name allow -->` on its own line immediately before the line to suppress, or at the end of the violating line.
+  - **One-off:** Put `<!-- rule-name allow -->` on its own line before the line to suppress (blank lines in between are OK), or at the end of the violating line.
   - **Block:** Put `<!-- rule-name disable -->` on its own line to turn the rule off; put `<!-- rule-name enable -->` on its own line to turn it back on.
     All lines between disable and enable (and after disable if there is no enable) are suppressed.
   Example: `<!-- no-empty-heading allow -->` on the previous line suppresses that heading's empty-section violation.
@@ -699,7 +699,7 @@ When reusing any rule, copy `utils.js` into your `.markdownlint-rules` (see [Reu
 When the file path matches any pattern, the rule is skipped for that file.
 This uses `pathMatchesAny` from `utils.js`.
 
-- **HTML comment suppress:** `isRuleSuppressedByComment(lines, lineNumber, ruleName)` - returns true when (1) the line or the previous line contains `<!-- ruleName allow -->`, or (2) the line is inside a block between `<!-- ruleName disable -->` and `<!-- ruleName enable -->` (used by all rules for per-line and block override).
+- **HTML comment suppress:** `isRuleSuppressedByComment(lines, lineNumber, ruleName)` - returns true when (1) the line ends with `<!-- ruleName allow -->`, or the first non-blank line above (skipping blank lines only) is solely that comment, or (2) the line is inside a block between `<!-- ruleName disable -->` and `<!-- ruleName enable -->` (used by all rules for per-line and block override).
   Also accepts markdownlint's cleared form (comment body replaced with dots).
 
 - **Heading and content:** `extractHeadings`, `iterateNonFencedLines`, `iterateProseLines`, `stripInlineCode`, `parseHeadingNumberPrefix`, `normalizeHeadingTitleForDup`, `normalizedTitleForDuplicate`, `RE_ATX_HEADING`, `RE_NUMBERING_PREFIX`.

markdownlint-rules/utils.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const path = require("node:path");
+
 /**
  * Shared helpers for markdownlint custom rules.
  * Used by heading and prose rules (duplicate headings, numbering, ASCII, arrows).
@@ -203,24 +205,45 @@ function globToRegExp(pattern) {
 
 /**
  * Match path against a single glob pattern. Path normalized to forward slashes.
- * Relative patterns match when path starts with pattern or pattern appears mid-path.
- * @param {string} path - File path to test
+ * Relative inputs use `path.normalize` before matching so e.g. `docs/../README.md`
+ * matches the same as `README.md`.
+ * A pattern with no `/` matches only project-root files: the path relative to
+ * `process.cwd()` must be a single segment below cwd, or one `..` segment then a
+ * filename (e.g. `../README.md` when linting from a subdir). Nested paths like
+ * `docs/README.md` still require `**` in the pattern.
+ * @param {string} filePath - File path to test (as markdownlint passes in `name`)
  * @param {string} pattern - Glob pattern
  * @returns {boolean}
  */
-function matchGlob(path, pattern) {
-  if (!path || !pattern) {
+function matchGlob(filePath, pattern) {
+  if (!filePath || !pattern) {
     return false;
   }
-  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
-  const re = globToRegExp(pattern);
-  if (re.test(normalized)) {
+  const normalized = path.normalize(filePath).replace(/\\/g, "/").replace(/^\.\//, "");
+  if (globToRegExp(pattern).test(normalized)) {
     return true;
   }
-  const isRelative =
-    pattern[0] !== "/" && pattern[0] !== "*" && !pattern.startsWith("./");
-  if (isRelative) {
-    return globToRegExp("**/" + pattern).test(normalized);
+  if (!pattern.includes("/")) {
+    let resolved;
+    try {
+      resolved = path.resolve(filePath);
+    } catch {
+      return false;
+    }
+    const rel = path.relative(process.cwd(), resolved).replace(/\\/g, "/");
+    if (!rel) {
+      return false;
+    }
+    let segmentForGlob = rel;
+    if (rel.startsWith("..")) {
+      if (!/^\.\.\/[^/]+$/.test(rel)) {
+        return false;
+      }
+      segmentForGlob = path.basename(resolved);
+    } else if (rel.includes("/")) {
+      return false;
+    }
+    return globToRegExp(pattern).test(segmentForGlob);
   }
   return false;
 }
@@ -311,10 +334,12 @@ function isRuleDisabledAtLine(lines, lineNumber, ruleName) {
 
 /**
  * Return true if a violation at the given line is suppressed by an HTML comment.
- * Suppression: (1) the line immediately before lineNumber is solely
- * `<!-- ruleName allow -->` (optional whitespace), or (2) the line at lineNumber
+ * Suppression: (1) the first non-blank line at or above lineNumber-1, scanning upward,
+ * is solely `<!-- ruleName allow -->` (optional whitespace), or (2) the line at lineNumber
  * ends with that comment (e.g. inline at end of line), or (3) the line is inside
  * a disable block (between `<!-- ruleName disable -->` and `<!-- ruleName enable -->`).
+ * Blank lines between the allow comment and the violating line are skipped so a
+ * comment can sit above a spaced-out paragraph (common under H1 intros).
  *
  * @param {string[]} lines - All document lines (1-based index: line at lines[lineNumber - 1])
  * @param {number} lineNumber - 1-based line number of the violation
@@ -328,8 +353,14 @@ function isRuleSuppressedByComment(lines, lineNumber, ruleName) {
   if (currentLine == null) return false;
   if (trimmedLineMatchesSuppress(String(currentLine).trim(), ruleName)) return true;
   if (lineNumber < 2) return false;
-  const prevLine = lines[lineNumber - 2];
-  return prevLine != null && trimmedLineMatchesSuppress(String(prevLine).trim(), ruleName);
+  for (let i = lineNumber - 2; i >= 0; i--) {
+    const t = String(lines[i] ?? "").trim();
+    if (t === "") {
+      continue;
+    }
+    return trimmedLineMatchesSuppress(t, ruleName);
+  }
+  return false;
 }
 
 /**

md_test_files/README.md

@@ -16,6 +16,7 @@
 - `**positive_heading_numbering_zero.md**` - 0-indexed H2 numbering (## 0., 1., 2. and subsections); passes with 0 errors.
 - `**positive_heading_title_case.md**` - Valid AP title case; headings with identifiers/file names in backticks (e.g. `sba_result`, `README.md`) and links with valid title-case or backticked-filename link text; passes with 0 errors.
 - `**positive_heading_like.md**` - Proper ATX headings and prose only; short title-case lines ending in colon with no prose after (or with a heading next) are not reported; passes with 0 errors.
+- `**positive_no_h1_content_suppress_immediate.md**` / `**positive_no_h1_content_suppress_blank_line.md**` - no-h1-content suppressed via `<!-- no-h1-content allow -->` on the previous line: prose immediately after the comment vs separated by a blank line; both pass with 0 errors.
 - `**negative_*.md**` - One file per failing scenario; lint each to verify the expected custom rule(s) fail.
 
 ## Negative Fixtures (Custom Rules Only)

md_test_files/expected_errors.yml

@@ -17,6 +17,12 @@ positive_heading_title_case.md:
 positive_heading_like.md:
   errors: []
 
+positive_no_h1_content_suppress_blank_line.md:
+  errors: []
+
+positive_no_h1_content_suppress_immediate.md:
+  errors: []
+
 negative_anchor_algo_placement.md:
   errors:
     - line: 10
@@ -299,9 +305,6 @@ negative_no_empty_heading.md:
     - line: 47
       rule: no-empty-heading
       message_contains: at least one line of content
-    - line: 51
-      rule: no-empty-heading
-      message_contains: at least one line of content
     - line: 63
       rule: no-empty-heading
       message_contains: at least one line of content

md_test_files/positive_no_h1_content_suppress_blank_line.md

@@ -0,0 +1,8 @@
+# Title
+<!-- no-h1-content allow -->
+
+Prose here.
+
+## Section
+
+Section content.

md_test_files/positive_no_h1_content_suppress_immediate.md

@@ -0,0 +1,7 @@
+# Title
+<!-- no-h1-content allow -->
+Prose here.
+
+## Section
+
+Section content.

test/markdownlint-rules/ascii-only.test.js

@@ -114,14 +114,22 @@ describe("ascii-only", () => {
     assert.strictEqual(errors.length, 0);
   });
 
-  it("allows non-ASCII when path matches relative pattern (utils matchGlob **/ branch)", () => {
+  it("allows non-ASCII when basename pattern uses explicit **/ (not implicit subdir match)", () => {
     const lines = ["Café"];
     const errors = runRule(rule, lines, {
-      anyUnicodePathPatterns: ["foo.md"],
+      anyUnicodePathPatterns: ["**/foo.md"],
     }, "sub/foo.md");
     assert.strictEqual(errors.length, 0);
   });
 
+  it("reports error for non-ASCII when only basename matches in a subdir (foo.md does not match sub/foo.md)", () => {
+    const lines = ["Arrow \u2192"];
+    const errors = runRule(rule, lines, {
+      anyUnicodePathPatterns: ["foo.md"],
+    }, "sub/foo.md");
+    assert.ok(errors.length >= 1);
+  });
+
   it("reports error when path does not match any unicode pattern (utils pathMatchesAny)", () => {
     const lines = ["Arrow \u2192"];
     const errors = runRule(rule, lines, {

test/markdownlint-rules/no-h1-content.test.js

@@ -123,6 +123,12 @@ describe("no-h1-content", () => {
     assert.strictEqual(errors.length, 0);
   });
 
+  it("reports no error when suppress comment is separated by blank lines from prose", () => {
+    const lines = ["# Title", "<!-- no-h1-content allow -->", "", "This is not allowed.", "## Section"];
+    const errors = runRule(rule, lines);
+    assert.strictEqual(errors.length, 0);
+  });
+
   it("reports error for code block under h1", () => {
     const lines = ["# Title", "```", "code", "```", "## Next"];
     const errors = runRule(rule, lines);

test/markdownlint-rules/utils.test.js

@@ -4,17 +4,70 @@
  * Unit tests for utils.js helpers used by custom rules (e.g. isRuleSuppressedByComment).
  */
 
+const path = require("node:path");
 const { describe, it } = require("node:test");
 const assert = require("node:assert");
-const { isRuleSuppressedByComment } = require("../../markdownlint-rules/utils.js");
+const { isRuleSuppressedByComment, matchGlob, pathMatchesAny } = require("../../markdownlint-rules/utils.js");
 
 describe("utils", () => {
+  describe("matchGlob", () => {
+    it("matches bare filename only at path root (single segment)", () => {
+      assert.strictEqual(matchGlob("README.md", "README.md"), true);
+      assert.strictEqual(matchGlob("docs/README.md", "README.md"), false);
+      assert.strictEqual(matchGlob("docs/README.md", "**/README.md"), true);
+    });
+
+    it("matches *.md only at root segment", () => {
+      assert.strictEqual(matchGlob("doc.md", "*.md"), true);
+      assert.strictEqual(matchGlob("sub/doc.md", "*.md"), false);
+      assert.strictEqual(matchGlob("sub/doc.md", "**/*.md"), true);
+    });
+
+    it("matches root basename when path is absolute (markdownlint passes full path)", () => {
+      const rootReadme = path.join(process.cwd(), "README.md");
+      const nestedReadme = path.join(process.cwd(), "docs", "README.md");
+      assert.strictEqual(matchGlob(rootReadme, "README.md"), true);
+      assert.strictEqual(matchGlob(nestedReadme, "README.md"), false);
+    });
+
+    it("normalizes relative paths with .. before matching (docs/../README.md)", () => {
+      assert.strictEqual(matchGlob("docs/../README.md", "README.md"), true);
+      assert.strictEqual(matchGlob("docs/../other/README.md", "README.md"), false);
+    });
+
+    it("matches one .. segment relative to cwd (../README.md from a subdir)", () => {
+      const parentReadme = path.resolve(process.cwd(), "..", "README.md");
+      assert.strictEqual(matchGlob(parentReadme, "README.md"), true);
+      assert.strictEqual(matchGlob(path.resolve(process.cwd(), "..", "other", "README.md"), "README.md"), false);
+    });
+  });
+
+  describe("pathMatchesAny", () => {
+    it("returns false when no pattern matches", () => {
+      assert.strictEqual(pathMatchesAny("a/b.md", ["x.md"]), false);
+    });
+
+    it("returns true when any pattern matches", () => {
+      assert.strictEqual(pathMatchesAny("README.md", ["other.md", "README.md"]), true);
+    });
+  });
+
   describe("isRuleSuppressedByComment", () => {
     it("returns true when previous line is solely the suppress comment", () => {
       const lines = ["<!-- no-empty-heading allow -->", "## Empty", "## Next"];
       assert.strictEqual(isRuleSuppressedByComment(lines, 2, "no-empty-heading"), true);
     });
 
+    it("returns true when suppress comment is separated by blank lines from the line", () => {
+      const lines = ["<!-- no-h1-content allow -->", "", "", "Intro paragraph.", "## Next"];
+      assert.strictEqual(isRuleSuppressedByComment(lines, 4, "no-h1-content"), true);
+    });
+
+    it("returns false when a non-blank line between target and suppress is not the comment", () => {
+      const lines = ["<!-- no-h1-content allow -->", "- [TOC](#toc)", "", "Prose.", "## Next"];
+      assert.strictEqual(isRuleSuppressedByComment(lines, 4, "no-h1-content"), false);
+    });
+
     it("returns true when current line ends with the suppress comment", () => {
       const lines = ["## Empty section <!-- no-empty-heading allow -->", "## Next"];
       assert.strictEqual(isRuleSuppressedByComment(lines, 1, "no-empty-heading"), true);