@@ -43,6 +43,11 @@ ascii-only:
     - "📊"
     - "⚠️"
 
+# document-length: disallow documents longer than maximum lines (default 1500)
+# - maximum: positive integer; default 1500
+document-length:
+  maximum: 1500
+
 # heading-title-case: AP-style headline capitalization; words in backticks ignored
 # heading-title-case:
 #   lowercaseWords: ["through", ...]  # optional; extends default list (add words)
 
@@ -31,6 +31,9 @@ Lint and docs-as-code tooling: custom [markdownlint](https://github.com/DavidAns
   - [no-heading-like-lines.js](markdownlint-rules/no-heading-like-lines.js) - no heading-like lines.
     - Report lines that look like headings but are not (e.g. `**Text:**`, `1. **Text**`); prompt use of real `#` headings.
     - Use when: ensuring real Markdown headings instead of bold/italic that look like headings.
+  - [document-length.js](markdownlint-rules/document-length.js) - maximum document length.
+    - Disallow documents longer than a configured number of lines (default 1500); reports on line 1 when over the limit.
+    - Use when: keeping individual docs under a line cap to encourage splitting.
   - [utils.js](markdownlint-rules/utils.js) - shared utilities
     - Heading/content helpers and path/glob matching; used by other rules.
       Do not register as a rule in markdownlint.
 
@@ -131,6 +131,23 @@ Order of entries matters: the first pattern that matches the anchor id is used.
 
 **Behavior:** Reports lines that look like headings but are not (e.g. `**Text:**`, `**Text**:`, `1. **Text**`, and italic variants). Prompts use of real `#` headings instead.
 
+### `document-length`
+
+**File:** `document-length.js`
+
+**Description:** Disallow documents longer than a configured number of lines.
+
+**Configuration:** In `.markdownlint.yml` (or `.markdownlint.json`) under `document-length`:
+
+```yaml
+document-length:
+  maximum: 1500   # optional; default 1500
+```
+
+- **`maximum`** (number, default `1500`): Maximum allowed line count. Must be a positive integer.
+
+**Behavior:** When the file has more than `maximum` lines, the rule reports a single error on line 1. The message includes the actual line count and the maximum and suggests splitting into smaller files.
+
 ### `ascii-only`
 
 **File:** `ascii-only.js`
 
@@ -0,0 +1,32 @@
+"use strict";
+
+/**
+ * markdownlint rule: disallow documents longer than a configured number of lines.
+ * Reports a single error on line 1 when the file exceeds the maximum.
+ *
+ * @param {object} params - markdownlint params (lines, name, config)
+ * @param {function(object): void} onError - Callback to report an error
+ */
+function ruleFunction(params, onError) {
+  const lines = params.lines;
+  const raw = params.config?.maximum;
+  const maximum =
+    typeof raw === "number" && Number.isInteger(raw) && raw >= 1 ? raw : 1500;
+
+  if (lines.length <= maximum) {
+    return;
+  }
+
+  onError({
+    lineNumber: 1,
+    detail: `Document has ${lines.length} lines (maximum ${maximum}). Consider splitting into smaller files.`,
+    context: lines[0] ?? "",
+  });
+}
+
+module.exports = {
+  names: ["document-length"],
+  description: "Disallow documents longer than a configured number of lines",
+  tags: ["length"],
+  function: ruleFunction,
+};
@@ -92,6 +92,16 @@ negative_duplicate_headings_normalized.md:
       rule: no-duplicate-headings-normalized
       message_contains: Duplicate heading title "overview"
 
+# negative_document_length.md is generated automatically (not committed).
+# See test-scripts/verify_markdownlint_fixtures.py: ensure_long_document_fixture() and
+# main() which creates it when missing; test_verify_markdownlint_fixtures.py generates
+# it in test_verify_document_length_generated_fixture then removes it.
+negative_document_length.md:
+  errors:
+    - line: 1
+      rule: document-length
+      message_contains: "maximum"
+
 negative_heading_like.md:
   errors:
     - line: 9
 
@@ -294,6 +294,24 @@ def test_verify_file_positive_integration(self):
         except (OSError, FileNotFoundError) as e:
             self.skipTest(f"markdownlint not runnable: {e}")
 
+    def test_verify_document_length_generated_fixture(self):
+        """Generate a 1501-line fixture, verify document-length error, then remove file."""
+        path = _REPO_ROOT / "md_test_files" / "negative_document_length.md"
+        expect_path = _REPO_ROOT / "md_test_files" / "expected_errors.yml"
+        if not expect_path.exists():
+            self.skipTest("expected_errors.yml not found")
+        v.ensure_long_document_fixture(path)
+        try:
+            self.assertIn("negative_document_length.md", v.load_expected_errors(expect_path))
+            cmd = v.find_markdownlint_cmd()
+            expectations = v.load_expected_errors(expect_path)
+            try:
+                v.verify_file(cmd, path, expectations)
+            except (OSError, FileNotFoundError) as e:
+                self.skipTest(f"markdownlint not runnable: {e}")
+        finally:
+            path.unlink(missing_ok=True)
+
     def test_verify_file_raises_when_exit_code_mismatch(self):
         """Exit code mismatch (expect 0 errors, got non-zero) raises AssertionError."""
         path = _REPO_ROOT / "md_test_files" / "positive.md"
 
@@ -27,6 +27,8 @@
 
 import yaml
 
+LONG_FIXTURE_LINES = 1501
+
 
 @dataclass(frozen=True)
 class ExpectedError:
@@ -60,11 +62,21 @@ def find_markdownlint_cmd() -> List[str]:
     return ["npx", "markdownlint-cli2"]
 
 
+def ensure_long_document_fixture(path: Path) -> None:
+    """Write a markdown file with LONG_FIXTURE_LINES lines so document-length rule fails."""
+    # Blank after heading to satisfy MD022; trailing newline to satisfy MD047
+    lines = ["# Title", ""] + [f"line {i}" for i in range(3, LONG_FIXTURE_LINES + 1)]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
 def list_fixture_files() -> List[Path]:
     """Return fixture paths: positive.md plus sorted negative_*.md in md_test_files."""
     md_dir = repo_root() / "md_test_files"
     positive = md_dir / "positive.md"
     negatives = sorted(md_dir.glob("negative_*.md"))
+    long_fixture = md_dir / "negative_document_length.md"
+    if long_fixture not in negatives:
+        negatives = sorted(negatives + [long_fixture])
     return [positive, *negatives]
 
 
@@ -311,6 +323,8 @@ def main() -> int:
     failures: List[str] = []
 
     for f in files:
+        if f.name == "negative_document_length.md" and not f.exists():
+            ensure_long_document_fixture(f)
         if verbose:
             exp_total = 0
             if f.name in expectations_by_file:
 
@@ -0,0 +1,77 @@
+"use strict";
+
+/**
+ * Unit tests for document-length: disallow documents longer than a configured
+ * maximum number of lines; reports one error on line 1 when over the limit.
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const rule = require("../../markdownlint-rules/document-length.js");
+const { runRule } = require("./run-rule.js");
+
+function makeLines(n) {
+  return Array.from({ length: n }, (_, i) => (i === 0 ? "# Title" : `line ${i + 1}`));
+}
+
+describe("document-length", () => {
+  it("reports no errors when lines.length <= maximum (default 1500)", () => {
+    const lines = makeLines(1500);
+    const errors = runRule(rule, lines);
+    assert.strictEqual(errors.length, 0);
+  });
+
+  it("reports one error when lines.length > maximum (1501 lines)", () => {
+    const lines = makeLines(1501);
+    const errors = runRule(rule, lines);
+    assert.strictEqual(errors.length, 1);
+    assert.strictEqual(errors[0].lineNumber, 1);
+    assert.ok(errors[0].detail.includes("1501") && errors[0].detail.includes("1500"));
+    assert.ok(errors[0].detail.includes("maximum") || errors[0].detail.includes("Consider splitting"));
+  });
+
+  it("respects custom maximum: 11 lines with max 10 reports one error", () => {
+    const lines = makeLines(11);
+    const errors = runRule(rule, lines, { maximum: 10 });
+    assert.strictEqual(errors.length, 1);
+    assert.strictEqual(errors[0].lineNumber, 1);
+    assert.ok(errors[0].detail.includes("11") && errors[0].detail.includes("10"));
+  });
+
+  it("respects custom maximum: 10 lines with max 10 reports no error", () => {
+    const lines = makeLines(10);
+    const errors = runRule(rule, lines, { maximum: 10 });
+    assert.strictEqual(errors.length, 0);
+  });
+
+  it("reports no error for 0 lines", () => {
+    const errors = runRule(rule, []);
+    assert.strictEqual(errors.length, 0);
+  });
+
+  it("reports no error for 1 line when max is 1", () => {
+    const errors = runRule(rule, ["only line"], { maximum: 1 });
+    assert.strictEqual(errors.length, 0);
+  });
+
+  it("reports one error for 2 lines when max is 1", () => {
+    const errors = runRule(rule, ["first", "second"], { maximum: 1 });
+    assert.strictEqual(errors.length, 1);
+    assert.strictEqual(errors[0].lineNumber, 1);
+  });
+
+  it("uses default maximum when config.maximum is not a positive integer", () => {
+    const lines = makeLines(1501);
+    const errors = runRule(rule, lines, { maximum: "1500" });
+    assert.strictEqual(errors.length, 1);
+    assert.ok(errors[0].detail.includes("1500"));
+  });
+
+  it("reports error with empty context when first line is undefined (over limit)", () => {
+    const lines = Array(2);
+    lines[1] = "second";
+    const errors = runRule(rule, lines, { maximum: 1 });
+    assert.strictEqual(errors.length, 1);
+    assert.strictEqual(errors[0].context, "");
+  });
+});