From 66937d21d7bc0a0749abbd1ab63a4e99bd5facbd Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Wed, 21 Oct 2026 06:05:13 +0200
Subject: [PATCH] docs: install the site packages for contributors

The contributor install line left out mkdocs-material and
pymdown-extensions, so pipeline step 8b (render site) was skipped.
The ranges are the ones deploy-site.yml installs, and a test reads
them from the workflow.
---
 CONTRIBUTING.md                 |  3 ++-
 scripts/generate_readme.py      |  3 ++-
 tests/test_contributing_text.py | 12 ++++++++++++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fa5b7e12..4860f55e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,7 +46,8 @@ Full walkthrough: [profiling guide](https://abdess.github.io/retrobios/wiki/prof
 The checks CI runs on a pull request (Python 3.12 or newer):
 
 ```bash
-pip install pyyaml "jsonschema[format-nongpl]" markdown
+pip install pyyaml "jsonschema[format-nongpl]" markdown \
+    "mkdocs-material>=9.7.5,<10" "pymdown-extensions>=10.14"
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --changed --strict  # each profile the branch adds or edits
diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py
index d901fc18..e0650551 100644
--- a/scripts/generate_readme.py
+++ b/scripts/generate_readme.py
@@ -754,7 +754,8 @@ Full walkthrough: [profiling guide]({link("wiki/profiling")}).
 The checks CI runs on a pull request (Python 3.12 or newer):
 
 ```bash
-pip install pyyaml "jsonschema[format-nongpl]" markdown
+pip install pyyaml "jsonschema[format-nongpl]" markdown \\
+    "mkdocs-material>=9.7.5,<10" "pymdown-extensions>=10.14"
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --changed --strict  # each profile the branch adds or edits
diff --git a/tests/test_contributing_text.py b/tests/test_contributing_text.py
index dda3c7a0..1f72f67d 100644
--- a/tests/test_contributing_text.py
+++ b/tests/test_contributing_text.py
@@ -70,6 +70,18 @@ class BeforeOpeningAPullRequest(unittest.TestCase):
         workflow = (REPO_ROOT / ".github" / "workflows" / "validate.yml").read_text(encoding="utf-8")
         self.assertIn("validate_schemas.py --source-only", workflow)
 
+    def test_it_installs_the_packages_the_site_render_needs(self):
+        """Without mkdocs-material and pymdown-extensions the pipeline's
+        render step (8b) is skipped for every contributor."""
+        deploy = (REPO_ROOT / ".github" / "workflows" / "deploy-site.yml").read_text(
+            encoding="utf-8"
+        )
+        specs = re.findall(r'"((?:mkdocs-material|pymdown-extensions)[^"]*)"', deploy)
+        self.assertEqual(len(specs), 2)
+        text = generate_readme.generate_contributing()
+        for spec in specs:
+            self.assertIn(f'"{spec}"', text)
+
 
 if __name__ == "__main__":
     unittest.main()