fix(formatting): collapse multiple blank lines after frontmatter and lists (#399)

Goldziher · Goldziher · commit 614f57681d88 · 2026-06-01T08:52:03.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,8 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.6.0] - 2026-05-31
-
 ### Added
 
 - **`convert()` accepts options as a bare `ConversionOptions`** in addition to
@@ -26,6 +24,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **spurious blank lines after frontmatter and lists (MD012)** (resolves #399). Block-level
+  emission now collapses runs of three or more consecutive newlines into exactly two, so
+  the frontmatter→body and list→next-block transitions no longer produce extra blank lines
+  that violate markdownlint MD012.
 - **autolinks: bare paths and filenames are no longer wrapped as autolinks** (resolves #397).
   Per GFM §6.5, autolinks require an absolute URI with a scheme — but the previous check only
   compared the link text to the `href`, so `<a href="foobar.png">foobar.png</a>` became the
diff --git a/crates/html-to-markdown/src/converter/main.rs b/crates/html-to-markdown/src/converter/main.rs
@@ -15,8 +15,8 @@ use std::collections::{BTreeMap, HashSet};
 
 use crate::converter::dom_context::DomContext;
 use crate::converter::main_helpers::{
-    extract_head_metadata, format_metadata_frontmatter, has_custom_element_tags, repair_with_html5ever,
-    trim_line_end_whitespace, trim_trailing_whitespace,
+    collapse_excess_blank_lines, extract_head_metadata, format_metadata_frontmatter, has_custom_element_tags,
+    repair_with_html5ever, trim_line_end_whitespace, trim_trailing_whitespace,
 };
 use crate::converter::plain_text::extract_plain_text;
 use crate::converter::preprocessing_helpers::{has_inline_block_misnest, should_drop_for_preprocessing};
@@ -299,6 +299,7 @@ pub fn convert_html_impl(
         extract_plain_text(&dom, parser, options)
     } else {
         trim_line_end_whitespace(&mut output);
+        collapse_excess_blank_lines(&mut output);
         output
     };
     let (document, tables) = finish_structure_collector(structure_collector);
diff --git a/crates/html-to-markdown/src/converter/main_helpers.rs b/crates/html-to-markdown/src/converter/main_helpers.rs
@@ -19,6 +19,34 @@ pub fn trim_trailing_whitespace(output: &mut String) {
     }
 }
 
+/// Collapse runs of three or more consecutive newlines into exactly two.
+///
+/// Block-level emitters append their own trailing newlines and the next block
+/// emitter typically prepends a leading newline, which can produce `\n\n\n`
+/// runs in transitions such as frontmatter → first block or list → next block.
+/// markdownlint's MD012 rule forbids multiple consecutive blank lines, so the
+/// final emission is normalized here. This intentionally preserves single
+/// blank lines (`\n\n`) — only runs of three or more newlines are collapsed.
+pub fn collapse_excess_blank_lines(output: &mut String) {
+    if !output.contains("\n\n\n") {
+        return;
+    }
+    let mut cleaned = String::with_capacity(output.len());
+    let mut consecutive = 0usize;
+    for ch in output.chars() {
+        if ch == '\n' {
+            consecutive += 1;
+            if consecutive <= 2 {
+                cleaned.push(ch);
+            }
+        } else {
+            consecutive = 0;
+            cleaned.push(ch);
+        }
+    }
+    *output = cleaned;
+}
+
 /// Remove trailing spaces/tabs from every line while preserving newlines.
 pub fn trim_line_end_whitespace(output: &mut String) {
     if output.is_empty() {
diff --git a/crates/html-to-markdown/tests/issue_399_md012_blank_lines.rs b/crates/html-to-markdown/tests/issue_399_md012_blank_lines.rs
@@ -0,0 +1,31 @@
+#![allow(missing_docs)]
+
+//! Regression test for issue #399: spurious blank lines after the YAML
+//! frontmatter and after lists produced markdown that violates markdownlint
+//! MD012 (no multiple consecutive blank lines). Block-level emission must
+//! collapse runs of more than one blank line so the output contains at most a
+//! single empty line between blocks.
+
+use html_to_markdown_rs::{ConversionOptions, convert};
+
+#[test]
+fn no_double_blank_line_after_frontmatter_or_list() {
+    let html =
+        "<head>\n  <title>Foobar</title>\n</head>\n<body>\n  <p>Baz</p><ul><li>qux</li></ul><p>Thud</p>\n</body>";
+    let options = ConversionOptions {
+        extract_metadata: true,
+        ..Default::default()
+    };
+    let result = convert(html, Some(options)).expect("conversion should succeed");
+    let content = result.content.unwrap_or_default();
+    assert_eq!(content, "---\ntitle: Foobar\n---\n\nBaz\n\n- qux\n\nThud\n");
+}
+
+#[test]
+fn no_triple_newline_between_blocks_without_frontmatter() {
+    let html = "<p>Baz</p><ul><li>qux</li></ul><p>Thud</p>";
+    let options = ConversionOptions::default();
+    let result = convert(html, Some(options)).expect("conversion should succeed");
+    let content = result.content.unwrap_or_default();
+    assert_eq!(content, "Baz\n\n- qux\n\nThud\n");
+}
