feat: heading-numbering support 0-based sections and multiple positive fixtures

- Treat section as 0-based when first numbered sibling's last segment is 0 (e.g. 0., 0.0., 1.0.).
- Rename positive.md to positive_general.md; add positive_heading_numbering_zero.md.
- Verifier and tests now support multiple positive_*.md fixtures.

Author: cypher0n3

.markdownlint.yml

@@ -35,7 +35,7 @@ ascii-only:
   allowedPathPatternsEmoji:
     - "markdownlint-rules/README.md"
   # allowedUnicode:
-  #   - "ń"   # additions on top of default (fixtures e.g. positive.md)
+  #   - "ń"   # additions on top of default (fixtures e.g. positive_general.md)
   # allowedUnicodeReplaceDefault: false  # true = use only allowedUnicode list, no default set
   allowedEmoji:
     - "✅"

CONTRIBUTING.md

@@ -35,7 +35,7 @@ These targets mirror the GitHub Actions workflows. Run them locally before pushi
 
 ### Markdownlint Tests (`make test-markdownlint`)
 
-- **Positive test**: `md_test_files/positive.md` must pass markdownlint (0 errors).
+- **Positive test**: `md_test_files/positive_general.md` (and other `positive_*.md`) must pass markdownlint (0 errors).
 - **Negative tests**: each `md_test_files/negative_*.md` file must **fail** markdownlint; the test suite fails if any negative file passes.
 - Same behavior as the [Markdownlint tests](.github/workflows/markdownlint-tests.yml) workflow.
 

README.md

@@ -21,7 +21,8 @@ Lint and docs-as-code tooling: custom [markdownlint](https://github.com/DavidAns
     - Use when: keeping most docs ASCII while allowing Unicode/emoji only in chosen files (e.g. i18n or release notes).
   - [heading-numbering.js](markdownlint-rules/heading-numbering.js) - heading numbering.
     - Enforce segment count by numbering root, sequential numbering per section, and consistent period style (e.g. `1. Title` vs `1 Title`).
-    - Use when: docs use numbered headings (e.g. `### 1.2.3 Title`) and you want structure and style consistent.
+      Default is 1-based (1., 2., 3.); if the first numbered heading in a section starts at 0 (e.g. `0.`, `0.0.`), that section is treated as 0-based and no error is reported.
+    - Use when: docs use numbered headings (e.g. `### 1.2.3 Title` or 0-based `### 0. Introduction`) and you want structure and style consistent.
   - [heading-title-case.js](markdownlint-rules/heading-title-case.js) - heading title case.
     - Enforce title case for headings; words in backticks ignored; configurable lowercase words (e.g. vs, and, the).
     - Use when: you want consistent capitalization of headings (first/last and major words capped; small words lowercase in the middle).
@@ -40,7 +41,7 @@ Lint and docs-as-code tooling: custom [markdownlint](https://github.com/DavidAns
     - Use when: copying the rule files; required by several of the rules above.
 
 - **JS linting** for the rule code: ESLint (recommended + complexity/max-lines + eslint-plugin-security), aligned with the GitHub Actions workflow.
-- **Markdownlint fixture tests**: [md_test_files/](md_test_files/README.md) includes positive/negative fixtures with explicit expected errors, verified by `test-scripts/verify_markdownlint_fixtures.py`.
+- **Markdownlint fixture tests**: [md_test_files/](md_test_files/README.md) includes positive_*.md and negative_*.md fixtures with explicit expected errors, verified by `test-scripts/verify_markdownlint_fixtures.py`.
 - **Rule unit tests**: Node `node:test` unit tests for each custom rule in `test/markdownlint-rules/` (including security tests for defensive regex handling and ReDoS awareness); run with `make test-rules` or `npm run test:rules`.
   CI runs `make test-rules-coverage` (fails if any rule file is below 90% line/statement coverage).
 - **Python unit tests**: `unittest` tests for [test-scripts/](test-scripts/README.md) in `test-scripts/test_*.py`; run with `make test-python`.
@@ -128,7 +129,7 @@ npm install
 - **`Makefile`** - Local targets (kept in sync with the workflows in `.github/workflows/`).
 - **`markdownlint-rules/`** - Custom rule modules (`*.js`) and [README](markdownlint-rules/README.md).
   Copy into other repos as `.markdownlint-rules`; do not register `utils.js`.
-- **`md_test_files/`** - Test fixtures: `positive.md` (must pass), `negative_*.md` (must fail).
+- **`md_test_files/`** - Test fixtures: `positive_*.md` (must pass), `negative_*.md` (must fail).
   See [md_test_files/README.md](md_test_files/README.md).
 - **`package.json`** - npm dependencies (ESLint, markdownlint-cli2, etc.).
 - **`test/markdownlint-rules/`** - Node `node:test` unit tests for each custom rule (`*.test.js`); run with `make test-rules`.

markdownlint-rules/README.md

@@ -327,7 +327,8 @@ The first occurrence is the reference; duplicates are reported with the line num
    The numbering root is the nearest ancestor heading that has no numbering (or document root, level 1).
    Example: H2 under doc root -> 1 segment; H3 under unnumbered `## Section` -> 1 segment; H4 under `### 1. First` -> 1 segment.
    Headings without a numeric prefix are ignored.
-2. **Section-scoped consistency:** For each section (siblings under the same parent), if any sibling has numbering then all siblings at that level must be numbered sequentially (e.g. 1., 2., 3.) and use consistent period style (all `## 1. Title` or all `## 1 Title`).
+2. **Section-scoped consistency:** For each section (siblings under the same parent), if any sibling has numbering then all siblings at that level must be numbered sequentially and use consistent period style (all `## 1. Title` or all `## 1 Title`).
+   **Index base:** Default is 1-based (e.g. 1., 2., 3.). If the first numbered sibling in a section has last segment `0` (e.g. `0.`, `0.0.`, `1.0.`), that section is treated as 0-based (0., 1., 2. or 0.0., 0.1., etc.) and no sequence error is reported.
    Unnumbered siblings in a numbered section are reported.
 
 ## Shared Helper

markdownlint-rules/heading-numbering.js

@@ -67,7 +67,7 @@ function getSiblings(sorted, parentIndex, i) {
 /**
  * Expected number for heading at index i within its section (parent prefix + sibling sequence).
  * Section-scoped: only used when at least one sibling has numbering.
- * 0-based when the first numbered sibling has numbering "0".
+ * 0-based when the first numbered sibling's last segment is "0" (e.g. "0", "0.0", "1.0").
  */
 function getExpectedNumberInSection(sorted, parentIndex, i) {
   const h = sorted[i];
@@ -93,7 +93,8 @@ function getExpectedNumberInSection(sorted, parentIndex, i) {
       ? parseHeadingNumberPrefix(firstNumbered.rawText).numbering
       : null;
   /* c8 ignore stop */
-  const startAtZero = firstNumbering === "0";
+  const lastSegment = firstNumbering.split(".").pop();
+  const startAtZero = lastSegment === "0";
   const nextNum = startAtZero ? myIdx : myIdx + 1;
   const prefix = parentNum ? parentNum + "." : "";
   return prefix + String(nextNum);

md_test_files/README.md

@@ -1,23 +1,24 @@
 # Markdown Test Fixtures
 
-- **positive.md** - Examples that pass all markdown standards. Lint should report 0 errors.
+- **positive_general.md** - Examples that pass all markdown standards. Lint should report 0 errors.
+- **positive_heading_numbering_zero.md** - 0-indexed H2 numbering (## 0., 1., 2. and subsections); passes 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)
 
-| File                                      | Expected custom rule(s)                                   |
-| ----------------------------------------- | --------------------------------------------------------- |
-| negative_anchor_algo_placement.md         | allow-custom-anchors (algo placement)                     |
-| negative_anchor_invalid_id.md             | allow-custom-anchors (id not in allowedIdPatterns)        |
-| negative_anchor_multiple.md               | allow-custom-anchors (multiple per line)                  |
-| negative_anchor_ref_placement.md          | allow-custom-anchors (ref placement)                      |
-| negative_anchor_spec_placement.md         | allow-custom-anchors (spec placement)                     |
-| negative_ascii_only.md                    | ascii-only                                                |
-| negative_duplicate_headings_normalized.md | no-duplicate-headings-normalized                          |
-| negative_heading_like.md                  | no-heading-like-lines                                     |
-| negative_heading_numbering.md             | heading-numbering (segment, sequence, period, unnumbered) |
-| negative_heading_title_case.md            | heading-title-case                                        |
-| negative_inline_html.md                   | allow-custom-anchors (attribute, id pattern, end-of-line) |
+| File                                      | Expected custom rule(s)                                                 |
+| ----------------------------------------- | ----------------------------------------------------------------------- |
+| negative_anchor_algo_placement.md         | allow-custom-anchors (algo placement)                                   |
+| negative_anchor_invalid_id.md             | allow-custom-anchors (id not in allowedIdPatterns)                      |
+| negative_anchor_multiple.md               | allow-custom-anchors (multiple per line)                                |
+| negative_anchor_ref_placement.md          | allow-custom-anchors (ref placement)                                    |
+| negative_anchor_spec_placement.md         | allow-custom-anchors (spec placement)                                   |
+| negative_ascii_only.md                    | ascii-only                                                              |
+| negative_duplicate_headings_normalized.md | no-duplicate-headings-normalized                                        |
+| negative_heading_like.md                  | no-heading-like-lines                                                   |
+| negative_heading_numbering.md             | heading-numbering (segment, sequence, period, unnumbered, zero-indexed) |
+| negative_heading_title_case.md            | heading-title-case                                                      |
+| negative_inline_html.md                   | allow-custom-anchors (attribute, id pattern, end-of-line)               |
 
 Note: some negative fixtures intentionally trigger built-in markdownlint rules in addition to custom rules (e.g. MD031/MD032/MD033), so the test suite can assert multiple errors on specific lines.
 

md_test_files/expected_errors.yml

@@ -2,7 +2,10 @@
 # Used by test-scripts/verify_markdownlint_fixtures.py.
 # Total expected count is derived from the length of the errors list.
 
-positive.md:
+positive_general.md:
+  errors: []
+
+positive_heading_numbering_zero.md:
   errors: []
 
 negative_anchor_algo_placement.md:
@@ -140,6 +143,15 @@ negative_heading_numbering.md:
     - line: 25
       rule: heading-numbering
       message_contains: Too Many Segments for H4
+    - line: 33
+      rule: heading-numbering
+      message_contains: expected "1" to match sibling
+    - line: 37
+      rule: heading-numbering
+      message_contains: expected "2" to match sibling
+    - line: 41
+      rule: heading-numbering
+      message_contains: expected "0.1" to match sibling
 
 negative_heading_title_case.md:
   errors:

md_test_files/negative_heading_numbering.md

@@ -2,7 +2,7 @@
 
 Lint: `npx markdownlint-cli2 md_test_files/negative_heading_numbering.md`
 
-Expect: heading-numbering (segment count, sequence, period style, unnumbered sibling). All examples are H3/H4 under one H2 so only this section is affected.
+Expect: heading-numbering (segment count, sequence, period style, unnumbered sibling, zero-indexed violations). First block is H3/H4 under one H2; second block covers zero-indexed numbering errors.
 
 ## Bad Heading Numbering
 
@@ -23,3 +23,19 @@ Wrong segment count: H3 under H2 must have 1 segment, not 2.
 ### 1.1 Wrong Segment Count
 
 #### 1.1.1 Too Many Segments for H4
+
+## Zero-Indexed Numbering (Negative Examples)
+
+0-based section: first heading is 0., so sequence must be 0, 1, 2, ... Violations below.
+
+### 0. Zero-Based Section
+
+### 2. Skip 1 (0-Based Sequence; Expected 1.)
+
+0-based subsections under 0.: first is 0.0., so next must be 0.1., not 0.2.
+
+### 0. Subsection Root (0-Based)
+
+#### 0.0. First Sub
+
+#### 0.2. Skip 0.1 (Expected 0.1.)

md_test_files/positive.md md_test_files/positive_general.mdmd_test_files/positive.md renamed to md_test_files/positive_general.md

@@ -2,7 +2,7 @@
 
 This file contains examples that should pass the Markdown standards enforced by markdownlint and the Python validators.
 
-It is intended to be linted explicitly via `npx markdownlint-cli2 md_test_files/positive.md`.
+It is intended to be linted explicitly via `npx markdownlint-cli2 md_test_files/positive_general.md`.
 
 ## Formatting
 
@@ -106,3 +106,23 @@ AP style: hyphenated compounds (each segment capitalized); "to" and "a" lowercas
 ### 5. Summary: The Results
 
 AP style: first word after a colon is capitalized (subphrase start).
+
+## Zero-Indexed Heading Numbering
+
+When the first numbered heading in a section starts at 0, the rule treats that section as 0-based and does not report errors.
+
+### 0. Introduction (Zero-Indexed)
+
+Content under first 0-based H3.
+
+#### 0.1 Zero Indexed Section
+
+### 1. First Topic
+
+### 2. Second Topic
+
+Subsections under a 0-based H3 also use 0-based numbering when the first subheading is 0.
+
+#### 2.1. First Subsection
+
+#### 2.2. Second Subsection

md_test_files/positive_heading_numbering_zero.md

@@ -0,0 +1,25 @@
+# Positive Fixture: 0-Indexed H2 Numbering
+
+Lint: `npx markdownlint-cli2 md_test_files/positive_heading_numbering_zero.md`
+
+This file should pass with zero errors. The first H2 is 0-indexed, so the rule treats the top-level section as 0-based.
+
+## 0. Introduction
+
+Content under the first H2 (0-based).
+
+## 1. First Section
+
+Content.
+
+### 1.0 First Section First Subsection
+
+Content.
+
+## 2. Second Section
+
+Subsections under this H2 use 0-based numbering when the first is 2.0.
+
+### 2.0. First Subsection
+
+### 2.1. Second Subsection