From 77c4857a46900a00c4714b9b9caa02080167a9af Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Tue, 20 Oct 2026 04:30:03 +0200
Subject: [PATCH] fix: a site preview writes its own config

generate_site --docs-dir sent the pages elsewhere but always rewrote the tracked mkdocs.yml, outside the lock taken on that folder, with the navigation of the work in progress. Two previews into two folders both wrote it. Another folder now gets <name>.mkdocs.yml beside it, docs_dir set and its paths rebased, which mkdocs builds with -f.
---
 scripts/generate_site.py      | 19 ++++++++++++++++++-
 tests/test_site_validation.py | 14 ++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/scripts/generate_site.py b/scripts/generate_site.py
index 68898f68..48f8a4c0 100644
--- a/scripts/generate_site.py
+++ b/scripts/generate_site.py
@@ -4116,6 +4116,22 @@ def _build_emulator_file_index(profiles: dict) -> dict[str, dict]:
     }
 
 
+def _mkdocs_config(docs: Path, text: str) -> tuple[Path, str]:
+    """Where the site's config goes, and its text for that place.
+
+    The tracked mkdocs.yml belongs to docs/. A preview into another folder
+    rewrote it anyway, with the navigation of work in progress, and mkdocs
+    kept reading docs/. Another folder gets its own config beside it, its
+    paths taken from there.
+    """
+    if os.path.normpath(str(docs)) == DOCS_DIR:
+        return Path("mkdocs.yml"), text
+    where = docs.parent
+    for relative in ("scripts/mkdocs_hooks.py", "docs_assets/overrides"):
+        text = text.replace(relative, os.path.relpath(relative, where).replace(os.sep, "/"))
+    return where / f"{docs.name}.mkdocs.yml", f"docs_dir: {docs.name}\n" + text
+
+
 # mkdocs.yml nav generator
 
 
@@ -4752,7 +4768,8 @@ validation:
   unrecognized_links: warn
   anchors: warn
 """
-    write_if_changed("mkdocs.yml", mkdocs_static + nav_yaml)
+    config_path, config_text = _mkdocs_config(Path(docs), mkdocs_static + nav_yaml)
+    write_if_changed(str(config_path), config_text)
 
     total_pages = (
         1  # home
diff --git a/tests/test_site_validation.py b/tests/test_site_validation.py
index 9f75980b..65733f59 100644
--- a/tests/test_site_validation.py
+++ b/tests/test_site_validation.py
@@ -306,5 +306,19 @@ class PlainHouseStyle(unittest.TestCase):
                 self.assertFalse(first.endswith(" - RetroBIOS"), first)
 
 
+class APreviewLeavesTheTrackedConfig(unittest.TestCase):
+    """--docs-dir moved the pages but still rewrote the tracked mkdocs.yml."""
+
+    def test_another_folder_gets_its_own_config(self):
+        from generate_site import _mkdocs_config
+
+        path, text = _mkdocs_config(Path("docs"), "hooks:\n  - scripts/mkdocs_hooks.py\n")
+        self.assertEqual(path, Path("mkdocs.yml"))
+        path, text = _mkdocs_config(Path("tmp/preview"), "hooks:\n  - scripts/mkdocs_hooks.py\n")
+        self.assertEqual(path, Path("tmp/preview.mkdocs.yml"))
+        self.assertTrue(text.startswith("docs_dir: preview\n"))
+        self.assertIn("../scripts/mkdocs_hooks.py", text)
+
+
 if __name__ == "__main__":
     unittest.main()