Fix GitHub Pages visual preview paths and regenerate visual docs during deploy

mgarcia01752 · mgarcia01752 · commit eb918208d367 · 2026-02-22T17:43:20.000-07:00
- switch generated MkDocs preview iframe URLs back to correct relative paths so they work on GitHub Pages project-site URLs
- preserve local MkDocs preview compatibility while avoiding root-relative path breakage on Pages
- update MkDocs Pages deploy workflow to regenerate visual docs from visual/ before building the site
- keep visual docs validation check after generation to ensure deterministic output
- resolve GitHub Pages runtime 404 behavior caused by preview pathing assumptions on project-prefixed URLs - 2026-02-22 17:43:20
diff --git a/.github/workflows/mkdocs-pages-deploy.yml b/.github/workflows/mkdocs-pages-deploy.yml
@@ -36,6 +36,9 @@ jobs:
       - name: Validate visual sanitization
         run: python tools/sanitize.py --check
 
+      - name: Generate visual docs from visual source of truth
+        run: python tools/docs/build_visual_docs.py
+
       - name: Validate generated visual docs
         run: python tools/docs/build_visual_docs.py --check
 
diff --git a/docs/visual/DOCSIS-3.0/DS-SCQAM-CodeErrorRate.md b/docs/visual/DOCSIS-3.0/DS-SCQAM-CodeErrorRate.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.0/DS-SCQAM-CodeErrorRate.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.0/DS-SCQAM-CodeErrorRate.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.0/DS-SCQAM-Stats.md b/docs/visual/DOCSIS-3.0/DS-SCQAM-Stats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.0/DS-SCQAM-Stats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.0/DS-SCQAM-Stats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.0/US-ATDMA-PreEqualization.md b/docs/visual/DOCSIS-3.0/US-ATDMA-PreEqualization.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.0/US-ATDMA-PreEqualization.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.0/US-ATDMA-PreEqualization.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.0/US-ATDMA-Stats.md b/docs/visual/DOCSIS-3.0/US-ATDMA-Stats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.0/US-ATDMA-Stats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.0/US-ATDMA-Stats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.1/DS-OFDM-ChannelStats.md b/docs/visual/DOCSIS-3.1/DS-OFDM-ChannelStats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.1/DS-OFDM-ChannelStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.1/DS-OFDM-ChannelStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.1/DS-OFDM-ProfileStats.md b/docs/visual/DOCSIS-3.1/DS-OFDM-ProfileStats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.1/DS-OFDM-ProfileStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.1/DS-OFDM-ProfileStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.1/DiplexConfiguration.md b/docs/visual/DOCSIS-3.1/DiplexConfiguration.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.1/DiplexConfiguration.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.1/DiplexConfiguration.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-3.1/US-OFDMA-ChannelStats.md b/docs/visual/DOCSIS-3.1/US-OFDMA-ChannelStats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-3.1/US-OFDMA-ChannelStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-3.1/US-OFDMA-ChannelStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-General/EventLog.md b/docs/visual/DOCSIS-General/EventLog.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-General/EventLog.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-General/EventLog.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/DOCSIS-General/InterfaceStats.md b/docs/visual/DOCSIS-General/InterfaceStats.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/DOCSIS-General/InterfaceStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../visual-previews/DOCSIS-General/InterfaceStats.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-GroupDelay.md b/docs/visual/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-GroupDelay.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-GroupDelay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-GroupDelay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-MIN_AVG_MAX.md b/docs/visual/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-MIN_AVG_MAX.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-MIN_AVG_MAX.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/ChannelEstimation/ChannelEstimation-Analysis-MIN_AVG_MAX.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-EchoDetection.md b/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-EchoDetection.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-EchoDetection.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-EchoDetection.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-GroupDelay.md b/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-GroupDelay.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-GroupDelay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-GroupDelay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-MinAvgMax.md b/docs/visual/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-MinAvgMax.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-MinAvgMax.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/OfdmaPreEqualization/OfdmaPreEqualization-Analysis-MinAvgMax.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/RxMER/RxMER-Analysis-MIn-Avg-Max.md b/docs/visual/MultiCapture/RxMER/RxMER-Analysis-MIn-Avg-Max.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/RxMER/RxMER-Analysis-MIn-Avg-Max.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/RxMER/RxMER-Analysis-MIn-Avg-Max.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/RxMER/RxMER-Analysis-OFDMA-Profile-Performance-1.md b/docs/visual/MultiCapture/RxMER/RxMER-Analysis-OFDMA-Profile-Performance-1.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/RxMER/RxMER-Analysis-OFDMA-Profile-Performance-1.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/RxMER/RxMER-Analysis-OFDMA-Profile-Performance-1.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/MultiCapture/RxMER/RxMER-Analysis-Rxmer-Heat-Map.md b/docs/visual/MultiCapture/RxMER/RxMER-Analysis-Rxmer-Heat-Map.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/MultiCapture/RxMER/RxMER-Analysis-Rxmer-Heat-Map.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/MultiCapture/RxMER/RxMER-Analysis-Rxmer-Heat-Map.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/Histogram/Histogram.md b/docs/visual/SingleCapture/Histogram/Histogram.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/Histogram/Histogram.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/Histogram/Histogram.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDM/GetCapture-ChanEst.md b/docs/visual/SingleCapture/OFDM/GetCapture-ChanEst.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDM/GetCapture-ChanEst.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDM/GetCapture-ChanEst.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDM/GetCapture-ConstellationDisplay.md b/docs/visual/SingleCapture/OFDM/GetCapture-ConstellationDisplay.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDM/GetCapture-ConstellationDisplay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDM/GetCapture-ConstellationDisplay.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDM/GetCapture-FecSummary.md b/docs/visual/SingleCapture/OFDM/GetCapture-FecSummary.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDM/GetCapture-FecSummary.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDM/GetCapture-FecSummary.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDM/GetCapture-ModulationProfile.md b/docs/visual/SingleCapture/OFDM/GetCapture-ModulationProfile.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDM/GetCapture-ModulationProfile.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDM/GetCapture-ModulationProfile.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDM/GetCapture-RxMER.md b/docs/visual/SingleCapture/OFDM/GetCapture-RxMER.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDM/GetCapture-RxMER.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDM/GetCapture-RxMER.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/docs/visual/SingleCapture/OFDMA/GetCapture-PreEqualization.md b/docs/visual/SingleCapture/OFDMA/GetCapture-PreEqualization.md
@@ -7,7 +7,7 @@
 
 ## Preview
 
-<iframe src="/visual-previews/SingleCapture/OFDMA/GetCapture-PreEqualization.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
+<iframe src="../../../../visual-previews/SingleCapture/OFDMA/GetCapture-PreEqualization.html" style="width:100%;height:900px;border:1px solid #ccc;border-radius:6px;"></iframe>
 
 Preview is best-effort. Some templates may rely on Postman-specific APIs that are not yet shimmed.
 
diff --git a/tools/docs/build_visual_docs.py b/tools/docs/build_visual_docs.py
@@ -401,8 +401,12 @@ def main(argv: list[str]) -> int:
                 changed_count += 1
                 written_count += 0 if check_only else 1
                 print(f"{'DRIFT' if check_only else 'WRITE'}: {preview_path.relative_to(repo_root)}")
-            # Use a site-root-relative path to avoid MkDocs directory-URL relative path issues.
-            preview_rel_from_page = Path("/") / preview_path.relative_to(docs_root)
+            # MkDocs serves markdown pages as directory URLs by default, e.g.
+            # docs/visual/foo/bar.md -> /visual/foo/bar/, so relative iframe paths
+            # must be computed from a virtual "bar/" directory, not page_path.parent.
+            # Relative URLs are required for GitHub Pages project sites so the repo
+            # path prefix is preserved.
+            preview_rel_from_page = Path(os_path_rel(page_path.with_suffix(""), preview_path))
 
         md_content = build_example_markdown(
             example=ex,
