diff --git a/.github/workflows/framework-tests.yml b/.github/workflows/framework-tests.yml
index 3822814..b095a71 100644
--- a/.github/workflows/framework-tests.yml
+++ b/.github/workflows/framework-tests.yml
@@ -48,6 +48,10 @@ jobs:
     name: Static + content checks
     runs-on: ubuntu-latest
     continue-on-error: true
+    # Bounds a hung `Install chromium` / apt-get step (observed stuck 30+ min
+    # with no failure — GitHub's default job timeout is 6 hours) so the run
+    # fails fast instead of sitting until that default kicks in.
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
@@ -116,6 +120,23 @@ jobs:
         working-directory: docs-theme-extras
         run: npm ci
 
+      # ubuntu-latest resolves apt's default mirror to a region-specific
+      # azure.archive.ubuntu.com endpoint that has repeatedly gone unreachable
+      # outright (apt-get update stalls on endless "Ign:" retries instead of
+      # failing) — same root cause as the timeout guard above. Point apt at
+      # the direct global mirror before Playwright's installer shells out to
+      # apt-get, instead of just waiting longer.
+      - name: Work around flaky azure.archive.ubuntu.com apt mirror
+        run: |
+          sudo sed -i 's|azure\.archive\.ubuntu\.com|archive.ubuntu.com|g' \
+            /etc/apt/sources.list \
+            /etc/apt/sources.list.d/*.sources \
+            /etc/apt/apt-mirrors.txt 2>/dev/null || true
+
+      - name: Install chromium
+        working-directory: docs-theme-extras
+        run: npx playwright install --with-deps chromium
+
       - name: Run static + content specs
         working-directory: docs-theme-extras
         env:
diff --git a/Makefile b/Makefile
index 1a64d63..4f18284 100644
--- a/Makefile
+++ b/Makefile
@@ -41,6 +41,13 @@ FRAMEWORK_EXTRAS_DIR ?= ../docs-theme-extras
 
 # One-time install: npm packages + Playwright browser binaries in the harness
 # checkout. ~120-180 MB, ~1-3 minutes.
+# Serving the HTML report binds a port and BLOCKS until interrupted, so it must
+# never run unattended: in CI it hangs the job, and in any scripted/non-tty run
+# it hangs the caller. Gate it on an interactive terminal AND the absence of CI.
+# The report is still written to playwright-report/ either way — view it with
+# `make framework-test-report`.
+SHOW_REPORT = if [ -t 1 ] && [ -z "$$CI" ]; then npx playwright show-report; fi
+
 .PHONY: framework-test-install
 framework-test-install:
 	@if [ ! -d "$(FRAMEWORK_EXTRAS_DIR)" ]; then \
@@ -60,7 +67,7 @@ framework-test:
 	hugo160 --gc --minify > .build.log 2>&1
 	cd $(FRAMEWORK_EXTRAS_DIR) && \
 		(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test; \
-		result=$$?; npx playwright show-report; exit $$result)
+		result=$$?; $(SHOW_REPORT); exit $$result)
 
 # Fastest loop — static specs only, no browser launch.
 .PHONY: framework-test-static
@@ -70,7 +77,7 @@ framework-test-static:
 	hugo160 --gc --minify > .build.log 2>&1
 	cd $(FRAMEWORK_EXTRAS_DIR) && \
 		(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test --project=static; \
-		result=$$?; npx playwright show-report; exit $$result)
+		result=$$?; $(SHOW_REPORT); exit $$result)
 
 # Chromium browser specs (tabs, mermaid, theme toggle, copy-md, console errors,
 # viewport, contrast).
@@ -81,7 +88,7 @@ framework-test-browser:
 	hugo160 --gc --minify > .build.log 2>&1
 	cd $(FRAMEWORK_EXTRAS_DIR) && \
 		(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test --project=browser; \
-		result=$$?; npx playwright show-report; exit $$result)
+		result=$$?; $(SHOW_REPORT); exit $$result)
 
 # Cross-browser desktop specs across chromium, firefox, and webkit.
 .PHONY: framework-test-cross-browser
@@ -94,7 +101,7 @@ framework-test-cross-browser:
 			--project=cross-browser-chromium \
 			--project=cross-browser-firefox \
 			--project=cross-browser-webkit; \
-		result=$$?; npx playwright show-report; exit $$result)
+		result=$$?; $(SHOW_REPORT); exit $$result)
 
 # Open the most recent Playwright HTML report.
 .PHONY: framework-test-report
diff --git a/go.mod b/go.mod
index 7a0ea4d..a8bf896 100644
--- a/go.mod
+++ b/go.mod
@@ -5,4 +5,4 @@ go 1.25.1
 // docs-theme-extras declares the hextra import itself (pinned to v0.12.3), so
 // hextra is a transitive dependency and is not listed here — matching
 // agentgateway / kgateway / ambientmesh. Its checksums stay in go.sum.
-require github.com/solo-io/docs-theme-extras v0.1.25 // indirect
+require github.com/solo-io/docs-theme-extras v0.2.0 // indirect
diff --git a/go.sum b/go.sum
index ed1bbca..860f50b 100644
--- a/go.sum
+++ b/go.sum
@@ -1,2 +1,2 @@
-github.com/solo-io/docs-theme-extras v0.1.25 h1:9SvHWXlrBxgk3/0NnV+JvkqQ7/rww4daIzdCYtSubVg=
-github.com/solo-io/docs-theme-extras v0.1.25/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg=
+github.com/solo-io/docs-theme-extras v0.2.0 h1:GShYCtM7oUC3UqHOqCPwPzsKe9jKdA1OXC0LVqo+h7w=
+github.com/solo-io/docs-theme-extras v0.2.0/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg=