feat(docs): render flat LABEL: paragraphs as Starlight asides in prettify()

docs/build-manual.py

@@ -412,19 +412,27 @@ def _as_aside(para: list[str]) -> str | None:
 
 
 def prettify(body: str, entry_name: str | None = None) -> str:
-    """Rewrite a body's indented code blocks for the website.
+    """Rewrite a body's indented code blocks and labeled asides for the website.
 
     Site-only: the man page and `config-help` keep reading the untouched
-    SSOT, where the indented form is exactly what pandoc wants.
+    SSOT, where the indented form and the `LABEL:` text are exactly what
+    pandoc/`config-help` want.
     """
     out: list[str] = []
     block: list[str] = []
+    flat: list[str] = []
     in_fence = False
 
+    def flush_flat() -> None:
+        out.append(_as_aside(flat) or "\n".join(flat))
+
     for line in body.split("\n"):
         if mt.FENCE_RE.match(line):
             in_fence = not in_fence
         if not in_fence and (line.startswith(INDENT) or (not line.strip() and block)):
+            if flat:
+                flush_flat()
+                flat.clear()
             block.append(line)
             continue
         if block:
@@ -433,8 +441,16 @@ def prettify(body: str, entry_name: str | None = None) -> str:
             out.append(_prettify_block(block, entry_name))
             out.append("")
             block = []
-        out.append(line)
+        if in_fence or not line.strip():
+            if flat:
+                flush_flat()
+                flat.clear()
+            out.append(line)
+        else:
+            flat.append(line)
 
+    if flat:
+        flush_flat()
     if block:
         while block and not block[-1].strip():
             block.pop()

docs/verify-manual.py

@@ -592,6 +592,47 @@ def test_as_aside_rejects_non_label_paragraphs():
         assert build_manual._as_aside(para) is None, f"{label} was wrongly asided"
 
 
+def test_prettify_flat_paragraphs_unchanged_when_not_labeled():
+    """Restructuring prettify()'s loop to buffer flat lines must not alter output for ordinary prose."""
+    import build_manual
+
+    body = "\n".join(
+        [
+            "## Heading",
+            "",
+            "First line of a paragraph",
+            "continued on a second line.",
+            "",
+            "A second paragraph.",
+        ]
+    )
+    assert build_manual.prettify(body) == body, "flat prose was altered by the aside buffering"
+
+
+def test_prettify_converts_a_flat_note_paragraph_to_an_aside():
+    """A `NOTE:` paragraph surrounded by ordinary prose becomes an <Aside>, prose is untouched."""
+    import build_manual
+
+    body = "\n".join(
+        [
+            "## Heading",
+            "",
+            "Ordinary prose before.",
+            "",
+            "NOTE: Something worth calling out.",
+            "",
+            "Ordinary prose after.",
+        ]
+    )
+    out = build_manual.prettify(body)
+    assert "## Heading" in out
+    assert "Ordinary prose before." in out
+    assert "Ordinary prose after." in out
+    assert (
+        '<Aside type="note" title="Note">\nSomething worth calling out.\n</Aside>' in out
+    ), f"note paragraph was not converted:\n{out}"
+
+
 def test_prettify_is_site_only():
     """The SSOT keeps the indented form the man-page pipeline depends on."""
     import build_manual