Add consecutive blank line normalization

Postprocessor now limits runs of 3+ empty lines to a maximum of 2,
preserving content inside fenced code blocks.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jdmonaco

CLAUDE.md

@@ -8,6 +8,7 @@ mdformat-space-control is an mdformat plugin that provides unified control over
 - **EditorConfig support**: Configure list indentation via `.editorconfig` files
 - **Tight list formatting**: Automatically removes unnecessary blank lines between list items
 - **Frontmatter spacing**: Normalizes spacing after YAML frontmatter (works with mdformat-frontmatter)
+- **Consecutive blank line normalization**: Limits runs of 3+ empty lines to a maximum of 2
 - **Trailing whitespace removal**: Strips trailing whitespace outside code blocks
 - **Escaped link repair**: Fixes malformed multi-line links from web-clipped content
 
@@ -39,7 +40,7 @@ mdformat_space_control/
   - `_render_list_item`: Per-item tight/loose formatting based on paragraph count
   - `_render_bullet_list`: Configurable indent + content-based tight/loose
   - `_render_ordered_list`: Configurable indent + content-based tight/loose
-  - `_postprocess_root`: Combined postprocessor applying frontmatter spacing, escaped link repair, and trailing whitespace removal
+  - `_postprocess_root`: Combined postprocessor applying frontmatter spacing, escaped link repair, consecutive blank line normalization, and trailing whitespace removal
 
 ## Plugin Extension Points
 
@@ -60,7 +61,7 @@ space_control = "mdformat_space_control"
 - **`tests/test_fixtures.py`**: Parametrized fixture tests
 - **`tests/test_editorconfig.py`**: EditorConfig-specific tests using temp directories
 - **`tests/test_frontmatter.py`**: Frontmatter spacing tests (requires mdformat-frontmatter)
-- **`tests/test_spacing_features.py`**: Trailing whitespace, hard breaks, escaped link repair tests
+- **`tests/test_spacing_features.py`**: Trailing whitespace, hard breaks, escaped link repair, consecutive blank line tests
 - **`tests/test_integration.py`**: Full-stack integration tests combining multiple features
 - **`tests/test_plugin_interactions.py`**: Tests for compatibility with other mdformat plugins
 

README.md

@@ -8,6 +8,7 @@ An [mdformat](https://github.com/executablebooks/mdformat) plugin that provides
 - **EditorConfig support**: Configure list indentation via `.editorconfig` files
 - **Tight list formatting**: Automatically removes unnecessary blank lines between list items
 - **Frontmatter spacing**: Normalizes spacing after YAML frontmatter (works with [mdformat-frontmatter](https://github.com/butler54/mdformat-frontmatter))
+- **Consecutive blank line normalization**: Limits runs of 3+ empty lines to a maximum of 2
 - **Trailing whitespace removal**: Strips trailing whitespace outside code blocks
 - **Escaped link repair**: Fixes malformed multi-line links from web-clipped content
 

mdformat_space_control/plugin.py

@@ -279,21 +279,58 @@ def _strip_trailing_whitespace(text: str) -> str:
     return "\n".join(result)
 
 
+def _normalize_consecutive_blank_lines(text: str) -> str:
+    """Limit consecutive blank lines to a maximum of 2.
+
+    Collapses runs of 3+ empty lines down to 2 empty lines (3 newlines).
+    Preserves content inside fenced code blocks.
+    """
+    lines = text.split("\n")
+    result = []
+    in_code_block = False
+    consecutive_empty = 0
+
+    for line in lines:
+        # Track code block state
+        stripped = line.strip()
+        if stripped.startswith("```") or stripped.startswith("~~~"):
+            in_code_block = not in_code_block
+
+        if in_code_block:
+            # Preserve everything inside code blocks
+            result.append(line)
+            consecutive_empty = 0
+        elif line == "":
+            consecutive_empty += 1
+            if consecutive_empty <= 2:
+                result.append(line)
+            # else: skip this empty line (collapse)
+        else:
+            consecutive_empty = 0
+            result.append(line)
+
+    return "\n".join(result)
+
+
 def _postprocess_root(text: str, node: RenderTreeNode, context: RenderContext) -> str:
     """Combined postprocessor for all space control features.
 
     Applies the following transformations in order:
     1. Frontmatter spacing normalization
     2. Escaped link repair
-    3. Trailing whitespace removal
+    3. Consecutive blank line normalization
+    4. Trailing whitespace removal
     """
     # 1. Frontmatter spacing
     text = _normalize_frontmatter_spacing(text)
 
     # 2. Repair escaped links (before trailing whitespace removal)
     text = _repair_escaped_links(text)
 
-    # 3. Trailing whitespace removal
+    # 3. Limit consecutive blank lines to 2
+    text = _normalize_consecutive_blank_lines(text)
+
+    # 4. Trailing whitespace removal
     text = _strip_trailing_whitespace(text)
 
     return text

tests/test_spacing_features.py

@@ -269,6 +269,113 @@ def test_link_with_prefix_text(self):
         assert result == expected
 
 
+class TestConsecutiveBlankLines:
+    """Tests for limiting consecutive blank lines.
+
+    Note: mdformat's AST-based rendering normalizes blank lines between
+    content blocks to a single blank line. The postprocessor can only work
+    on the rendered output, which has already been normalized.
+
+    These tests verify the postprocessor correctly handles:
+    1. Already-normalized content (pass-through)
+    2. Code blocks (preserve internal blank lines)
+    3. Direct function testing for edge cases
+    """
+
+    def test_mdformat_normalizes_multiple_blank_lines(self):
+        """mdformat normalizes multiple blank lines to one during rendering."""
+        # This verifies the expected behavior - mdformat already handles this
+        input_text = "First paragraph.\n\n\n\nSecond paragraph.\n"
+        expected = "First paragraph.\n\nSecond paragraph.\n"
+        result = mdformat.text(input_text, extensions={"space_control"})
+        assert result == expected
+
+    def test_single_empty_line_unchanged(self):
+        """Single empty line should remain unchanged."""
+        input_text = "First.\n\nSecond.\n"
+        expected = "First.\n\nSecond.\n"
+        result = mdformat.text(input_text, extensions={"space_control"})
+        assert result == expected
+
+    def test_code_block_preserved(self):
+        """Empty lines inside code blocks should be preserved."""
+        input_text = "Text.\n\n```\n\n\n\n\ncode\n\n\n\n\n```\n\nMore text.\n"
+        expected = "Text.\n\n```\n\n\n\n\ncode\n\n\n\n\n```\n\nMore text.\n"
+        result = mdformat.text(input_text, extensions={"space_control"})
+        assert result == expected
+
+
+class TestConsecutiveBlankLinesFunction:
+    """Direct tests for _normalize_consecutive_blank_lines function.
+
+    These tests verify the function works correctly in isolation,
+    independent of mdformat's rendering normalization.
+    """
+
+    def test_three_empty_lines_reduced_to_two(self):
+        """Three empty lines should be reduced to two."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "First paragraph.\n\n\n\nSecond paragraph.\n"
+        expected = "First paragraph.\n\n\nSecond paragraph.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_many_empty_lines_reduced_to_two(self):
+        """Many empty lines should be reduced to two."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "First.\n\n\n\n\n\n\nSecond.\n"
+        expected = "First.\n\n\nSecond.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_two_empty_lines_unchanged(self):
+        """Two empty lines should remain unchanged."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "First.\n\n\nSecond.\n"
+        expected = "First.\n\n\nSecond.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_single_empty_line_unchanged(self):
+        """Single empty line should remain unchanged."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "First.\n\nSecond.\n"
+        expected = "First.\n\nSecond.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_code_block_preserved(self):
+        """Empty lines inside code blocks should be preserved."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "Text.\n\n```\n\n\n\n\ncode\n\n\n\n\n```\n\nMore text.\n"
+        expected = "Text.\n\n```\n\n\n\n\ncode\n\n\n\n\n```\n\nMore text.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_multiple_sections(self):
+        """Multiple sections with excess blank lines."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "# One\n\n\n\n\nPara.\n\n\n\n\n# Two\n"
+        expected = "# One\n\n\nPara.\n\n\n# Two\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+    def test_tilde_code_block_preserved(self):
+        """Empty lines inside tilde-fenced code blocks should be preserved."""
+        from mdformat_space_control.plugin import _normalize_consecutive_blank_lines
+
+        input_text = "Text.\n\n~~~\n\n\n\n\ncode\n\n\n\n\n~~~\n\nMore text.\n"
+        expected = "Text.\n\n~~~\n\n\n\n\ncode\n\n\n\n\n~~~\n\nMore text.\n"
+        result = _normalize_consecutive_blank_lines(input_text)
+        assert result == expected
+
+
 class TestIntegration:
     """Integration tests for multiple features working together."""