From 1c671d71acebbedb371746291e47cdba82c5de05 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Sun, 26 Jul 2026 20:43:07 -0400
Subject: [PATCH] feat(docs): promote pages with asides or file trees to .mdx

---
 docs/build-manual.py  | 28 ++++++++++++++++++++++++----
 docs/verify-manual.py | 26 ++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/docs/build-manual.py b/docs/build-manual.py
index d43571c..f9d670d 100644
--- a/docs/build-manual.py
+++ b/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})
diff --git a/docs/verify-manual.py b/docs/verify-manual.py
index ed6e8cb..7377692 100644
--- a/docs/verify-manual.py
+++ b/docs/verify-manual.py
@@ -680,6 +680,32 @@ def test_customization_notes_render_as_aside():
     assert "</Aside>" in out
 
 
+def test_site_promotes_pages_with_asides_or_filetrees_to_mdx():
+    """A page whose rendered content contains <Aside> or <FileTree> is written as .mdx."""
+    import build_manual
+
+    docs = Path(__file__).parent
+    with tempfile.TemporaryDirectory() as d:
+        out = Path(d)
+        build_manual.build_site(docs / "manual", out)
+
+        assert (out / "10-personalization.mdx").exists(), "FileTree page was not promoted to .mdx"
+        assert not (out / "10-personalization.md").exists(), "old .md sibling was left behind"
+
+        assert (out / "11-viewing-this-manual.mdx").exists(), "Aside page (NOTE) was not promoted to .mdx"
+
+        assert (out / "07-customization.mdx").exists(), "Aside page (rewritten NOTE) was not promoted to .mdx"
+
+        assert (out / "01-configuration-variables.md").exists(), "plain page was wrongly promoted to .mdx"
+        assert not (out / "01-configuration-variables.mdx").exists(), "plain page should stay .md"
+
+        text = (out / "10-personalization.mdx").read_text()
+        assert "import { FileTree } from '@astrojs/starlight/components';" in text
+
+        text2 = (out / "11-viewing-this-manual.mdx").read_text()
+        assert "import { Aside } from '@astrojs/starlight/components';" in text2
+
+
 def test_prettify_is_site_only():
     """The SSOT keeps the indented form the man-page pipeline depends on."""
     import build_manual