spans
+ if self._in_inline_code:
+ self._emit(data)
+ return
+ # Collapse all whitespace (including newlines) per HTML rules
+ text = re.sub(r"\s+", " ", data)
+ # Suppress whitespace-only text nodes between table structural
+ # elements (indentation from source HTML) to prevent leading
+ # spaces from breaking Markdown table row alignment.
+ if self._in_table and not self._in_cell and not text.strip():
+ return
+ self._emit(text)
+
+ def handle_entityref(self, name: str) -> None:
+ if self._skip_depth:
+ return
+ self._emit(html.unescape(f"&{name};"))
+
+ def handle_charref(self, name: str) -> None:
+ if self._skip_depth:
+ return
+ self._emit(html.unescape(f"&#{name};"))
+
+ # ------------------------------------------------------------------
+ # Flush pending buffers (handles truncated HTML from capped fetches)
+ # ------------------------------------------------------------------
+ def flush_pending(self) -> None:
+ """Flush any open side-buffers into ``_out``.
+
+ Called after ``close()`` to recover content from truncated HTML
+ where closing tags were never seen (common when ``_fetch_page_text``
+ caps the download by byte count).
+ """
+ # Flush innermost buffers first so their content propagates outward.
+
+ if self._in_link:
+ self._finish_link()
+
+ if self._in_inline_code:
+ self._in_inline_code = False
+ self._emit("`")
+
+ self._finish_cell()
+ self._finish_row()
+
+ if self._in_pre:
+ raw = "".join(self._pre_parts)
+ self._in_pre = False
+ block = "```\n" + raw + "\n```"
+ self._emit("\n\n" + block + "\n\n")
+
+ # Flatten any open blockquote buffers (innermost first)
+ while self._bq_stack:
+ content = "".join(self._bq_stack.pop())
+ prefixed = self._prefix_blockquote(content)
+ if not prefixed:
+ continue
+ if self._bq_stack:
+ self._bq_stack[-1].append("\n\n" + prefixed + "\n\n")
+ else:
+ self._out.append("\n\n" + prefixed + "\n\n")
+
+
+# ------------------------------------------------------------------
+# Post-processing
+# ------------------------------------------------------------------
+def _cleanup(text: str) -> str:
+ """Normalize whitespace and blank lines in the final output.
+
+ Preserves content inside fenced code blocks verbatim so that
+ intentional blank lines in ```` content are not collapsed.
+ """
+ lines = text.split("\n")
+ out: list[str] = []
+ in_fence = False
+ blank_run = 0
+
+ for line in lines:
+ stripped = line.rstrip(" \t")
+ if stripped.startswith("```"):
+ in_fence = not in_fence
+ blank_run = 0
+ out.append(stripped)
+ continue
+
+ if in_fence:
+ # Preserve code block content exactly as-is
+ out.append(line)
+ continue
+
+ if not stripped:
+ blank_run += 1
+ if blank_run <= 1:
+ out.append("")
+ continue
+
+ blank_run = 0
+ out.append(stripped)
+
+ return "\n".join(out).strip()
+
+
+# ------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------
+def html_to_markdown(source_html: str) -> str:
+ """Convert an HTML string to Markdown.
+
+ Handles headings, links, bold/italic, lists (ordered and unordered),
+ tables, blockquotes, code blocks, and HTML entities. ``