fix(tree_renderer): truncate overlong node titles in summary headings

openkb/tree_renderer.py

@@ -15,6 +15,22 @@ def _yaml_frontmatter(source_name: str, doc_id: str, description: str = "") -> s
     return "---\n" + "\n".join(lines) + "\n---\n"
 
 
+_MAX_TITLE_LEN = 80
+
+
+def _short_title(title: str) -> str:
+    """Truncate a title for heading display.
+
+    The no-TOC fallback structure generator sometimes copies an entire
+    source sentence verbatim into ``title`` when there's no natural short
+    heading to extract; left unshortened that produces unreadable
+    multi-line Markdown headings (see PageIndex#341).
+    """
+    if len(title) <= _MAX_TITLE_LEN:
+        return title
+    return title[:_MAX_TITLE_LEN].rstrip() + "…"
+
+
 def _render_nodes_summary(nodes: list[dict], depth: int) -> str:
     """Recursively render nodes for the *summary* view (summaries only)."""
     lines: list[str] = []
@@ -26,7 +42,7 @@ def _render_nodes_summary(nodes: list[dict], depth: int) -> str:
         summary = node.get("summary", "")
         children = node.get("nodes", [])
 
-        lines.append(f"{heading_prefix} {title} (pages {start}–{end})\n")
+        lines.append(f"{heading_prefix} {_short_title(title)} (pages {start}–{end})\n")
         if summary:
             lines.append(f"Summary: {summary}\n")
         if children:

tests/test_tree_renderer.py

@@ -52,6 +52,38 @@ def test_summary_md_has_type_and_description():
     assert 'full_text: "sources/my-doc.json"' in md
 
 
+def test_overlong_title_is_truncated_in_heading():
+    long_title = (
+        "This is an entire source sentence copied verbatim into the title "
+        "field because the no-TOC fallback found no natural short heading "
+        "to extract from this section of the document."
+    )
+    tree = {
+        "structure": [
+            {
+                "title": long_title,
+                "start_index": 1,
+                "end_index": 2,
+                "summary": "x",
+                "nodes": [],
+            }
+        ]
+    }
+    md = render_summary_md(tree, "my-doc", "doc-123")
+    assert long_title not in md
+    assert f"# {long_title[:80]}…" in md
+
+
+def test_short_title_is_not_truncated():
+    tree = {
+        "structure": [
+            {"title": "Background", "start_index": 1, "end_index": 2, "summary": "x", "nodes": []}
+        ]
+    }
+    md = render_summary_md(tree, "my-doc", "doc-123")
+    assert "# Background (pages 1–2)" in md
+
+
 def test_summary_full_text_quoted_yaml_safe():
     import yaml