feat(docs): promote pages with asides or file trees to .mdx

docs/build-manual.py

@@ -594,6 +594,24 @@ def _split_entries(body: str) -> tuple[str, list[tuple[str, str]]]:
     return intro, entries
 
 
+ASTRO_ASIDE_COMPONENTS = {"<Aside": "Aside", "<FileTree": "FileTree"}
+
+
+def _write_prettified(target: Path, fm: dict, content: str) -> None:
+    """Write a prettified page, promoting to .mdx when it needs a component import.
+
+    A page stays .md (prettify()'s default, no imports) unless its rendered
+    content actually contains an <Aside> or <FileTree> — the only two
+    components a prettified (non-hand-built) page can contain.
+    """
+    needed = [name for marker, name in ASTRO_ASIDE_COMPONENTS.items() if marker in content]
+    if needed:
+        imports = f"import {{ {', '.join(needed)} }} from '@astrojs/starlight/components';\n\n"
+        target = target.with_suffix(".mdx")
+        content = imports + content
+    target.write_text(mt.serialize(fm, content))
+
+
 def build_site(root: Path, out: Path) -> list[dict]:
     """Write the Starlight content tree. Returns the sidebar structure."""
     if out.exists():
@@ -616,7 +634,7 @@ def build_site(root: Path, out: Path) -> list[dict]:
         if not is_function_dir:
             target = out / rel
             target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(mt.serialize(_page_fm(fm), prettify(body)))
+            _write_prettified(target, _page_fm(fm), prettify(body))
             if rel.name != "index.md":
                 sidebar.append({"label": fm["title"], "link": "/" + rel.stem + "/"})
             continue
@@ -633,7 +651,7 @@ def build_site(root: Path, out: Path) -> list[dict]:
         if rel.name == "index.md":
             target = out / slug_dir / "index.md"
             target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(mt.serialize(_page_fm(fm), prettify(body)))
+            _write_prettified(target, _page_fm(fm), prettify(body))
             # Built explicitly rather than by `autogenerate`, which labels
             # each group with its raw directory slug and republishes this
             # index as a child of the group it already titles.
@@ -658,8 +676,10 @@ def build_site(root: Path, out: Path) -> list[dict]:
             entry_fm = {"title": title}
             if desc:
                 entry_fm["description"] = desc
-            (cat_dir / f"{entry_slug}.md").write_text(
-                mt.serialize(entry_fm, prettify(entry_body, title.split()[0]))
+            _write_prettified(
+                cat_dir / f"{entry_slug}.md",
+                entry_fm,
+                prettify(entry_body, title.split()[0]),
             )
             href = f"/{slug_dir}/{category}/{entry_slug}/"
             links.append({"label": title, "link": href})