Collapse runs of blank lines in transformer markdown output (#61480)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/article-api/lib/normalize-markdown.ts

@@ -0,0 +1,25 @@
+/**
+ * Post-processing for transformer-produced markdown that is about to be sent
+ * to the client (via the `.md` URL suffix, `Accept: text/markdown`, or the
+ * article-body API). Kept intentionally small so the same rules apply to
+ * every transformer's output without each one having to opt in.
+ */
+
+/**
+ * Collapse runs of 3+ consecutive newlines down to 2 (i.e. at most one blank
+ * line between blocks). Transformers that render conditional sections often
+ * leave behind multiple blank lines when sections are empty; the rendered
+ * markdown is otherwise valid but visually noisy in the `.md` output.
+ */
+export function collapseBlankLines(content: string): string {
+  return content.replace(/\n{3,}/g, '\n\n')
+}
+
+/**
+ * Apply every normalization step that should run on transformer-produced
+ * markdown before it leaves the server. Centralized so new rules (e.g.
+ * trailing-whitespace stripping) can be added in one place.
+ */
+export function normalizeRenderedMarkdown(content: string): string {
+  return collapseBlankLines(content)
+}

src/article-api/middleware/article-body.ts

@@ -7,6 +7,7 @@ import features from '@/versions/middleware/features'
 import glossaries from '@/frame/middleware/context/glossaries'
 import dataTables from '@/data-directory/middleware/data-tables'
 import { transformerRegistry } from '@/article-api/transformers'
+import { normalizeRenderedMarkdown } from '@/article-api/lib/normalize-markdown'
 import { allVersions } from '@/versions/lib/all-versions'
 import type { Page } from '@/types'
 
@@ -72,5 +73,7 @@ export async function getArticleBody(req: ExtendedRequestWithPageInfo) {
     effectiveApiVersion = allVersions[currentVersion].latestApiVersion || undefined
   }
 
-  return await transformer.transform(page, pathname, renderingReq.context, effectiveApiVersion)
+  return normalizeRenderedMarkdown(
+    await transformer.transform(page, pathname, renderingReq.context, effectiveApiVersion),
+  )
 }

src/article-api/tests/normalize-markdown.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'vitest'
+
+import { collapseBlankLines, normalizeRenderedMarkdown } from '@/article-api/lib/normalize-markdown'
+
+describe('collapseBlankLines', () => {
+  test('collapses 3+ newlines down to 2', () => {
+    const input = 'one\n\n\n\ntwo'
+    expect(collapseBlankLines(input)).toBe('one\n\ntwo')
+  })
+
+  test('leaves single blank lines untouched', () => {
+    const input = 'one\n\ntwo'
+    expect(collapseBlankLines(input)).toBe('one\n\ntwo')
+  })
+
+  test('leaves single newlines untouched', () => {
+    const input = 'one\ntwo'
+    expect(collapseBlankLines(input)).toBe('one\ntwo')
+  })
+
+  test('handles multiple runs across the document', () => {
+    const input = 'a\n\n\nb\n\n\n\nc\n\nd'
+    expect(collapseBlankLines(input)).toBe('a\n\nb\n\nc\n\nd')
+  })
+
+  test('preserves trailing newline', () => {
+    const input = 'one\n\n\ntwo\n'
+    expect(collapseBlankLines(input)).toBe('one\n\ntwo\n')
+  })
+
+  test('also collapses blank-line runs inside fenced code blocks', () => {
+    // Markdown preserves blank lines inside ``` fences in the rendered
+    // <pre><code>, so this regex does change rendered code-block output.
+    // That is intentional: 3+ blank lines in a code sample is noise we want
+    // to collapse the same way we do everywhere else.
+    const input = 'before\n\n```\ncode\n\n\n\nmore code\n```\n\nafter'
+    expect(collapseBlankLines(input)).toBe('before\n\n```\ncode\n\nmore code\n```\n\nafter')
+  })
+})
+
+describe('normalizeRenderedMarkdown', () => {
+  test('applies blank-line collapsing', () => {
+    expect(normalizeRenderedMarkdown('a\n\n\n\nb')).toBe('a\n\nb')
+  })
+})

src/frame/middleware/render-page.ts

@@ -11,6 +11,7 @@ import statsd, { adaptForTimer } from '@/observability/lib/statsd'
 import type { ExtendedRequest } from '@/types'
 import { allVersions } from '@/versions/lib/all-versions'
 import { transformerRegistry } from '@/article-api/transformers'
+import { normalizeRenderedMarkdown } from '@/article-api/lib/normalize-markdown'
 import { minimumNotFoundHtml } from '../lib/constants'
 import { contentTypeCacheControl, defaultCacheControl } from './cache-control'
 import { nextHandleRequest } from './next'
@@ -113,7 +114,9 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
     // causes renderTitle/renderProp to output markdown instead of HTML,
     // which breaks the cheerio-based unwrap logic.
     const transformerContext = { ...context, markdownRequested: false }
-    req.context.renderedPage = await transformer.transform(page, path, transformerContext)
+    req.context.renderedPage = normalizeRenderedMarkdown(
+      await transformer.transform(page, path, transformerContext),
+    )
   } else {
     req.context.renderedPage = await buildRenderedPage(req)
     req.context.miniTocItems = buildMiniTocItems(req)