Serve everything from the site itself, and keep it that way

Reading the docs made every visitor's browser contact Google for Roboto and
GitHub for star counts. Neither is something a publicly funded project should
hand a classroom's IP addresses to for a documentation page.

Material requests the font unless theme.font is false, and mounts a component
on data-md-component="source" that calls api.github.com per page view;
overrides/partials/source.html is the theme's partial with that attribute
removed, so the repository link stays and only the counts go. Text now uses the
system font stack. The Swagger validator badge was already off by default.

Since all three are defaults that return on their own, tools/hooks.py now walks
the generated site after each build and fails if any link, script, image, frame
or CSS url() points at an absolute URL. Hyperlinks are exempt - a visitor
following one is not the site phoning home.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Staacks

CLAUDE.md

@@ -91,6 +91,34 @@ and the rules common to all modules.
 This structure is deliberately the one phase 3's generator should emit, so that generated pages can
 be diffed against the hand-written ones page by page.
 
+## The site makes no third-party requests
+
+Reading this site must not make a visitor's browser contact anyone but the host serving it. phyphox
+is used in classrooms, largely in Europe, by a publicly funded project — a documentation page is
+not a reason to hand anyone's IP address to a third party.
+
+Three defaults had to be turned off, and each would come back on its own:
+
+- **Google Fonts.** Material requests Roboto from `fonts.googleapis.com` on every page unless
+  `theme.font` is `false`. Any font *name* there reintroduces the request; the site uses the system
+  stack instead.
+- **GitHub stars.** With `repo_url` set, Material mounts a component on
+  `data-md-component="source"` that calls `api.github.com` per page view.
+  `overrides/partials/source.html` is a copy of the theme's partial with that attribute removed —
+  the link and icon stay, only the counts go. **It is a copy, so re-check it against the theme when
+  bumping mkdocs-material.**
+- **The Swagger validator badge.** Swagger UI posts the spec URL to `validator.swagger.io` by
+  default. `mkdocs-swagger-ui-tag` already defaults `validatorUrl` to `none`; do not set it to
+  anything else.
+
+`tools/hooks.py` enforces this in `on_post_build`: it walks the generated site and fails the build
+if any `<link>`, `<script>`, `<img>`, `<iframe>` or CSS `url()`/`@import` points at an absolute URL.
+Ordinary hyperlinks are fine — a visitor choosing to follow one is not the site phoning home — so
+`rel` values that describe a relationship without fetching (`canonical` and friends) are exempt.
+
+If a future feature genuinely needs an external asset, vendor it into `docs/assets` rather than
+relaxing the check.
+
 ## The inconsistency mechanism
 
 phyphox is implemented independently several times over — Android, iOS, the Blockly editor, the

README.md

@@ -20,6 +20,11 @@ python3 -m venv .venv
 .venv/bin/mkdocs build     # static HTML into site/
 ```
 
+The built site is fully self-contained: reading it makes a visitor's browser
+contact nothing but the host serving it. No web fonts, no analytics, no
+star-count lookups, no CDN. The build fails if that stops being true, so if you
+add something that pulls in an external asset, vendor the asset instead.
+
 CI builds with `--strict`, which turns broken internal links and unknown
 navigation entries into errors, so build that way before pushing:
 

mkdocs.yml

@@ -21,6 +21,14 @@ validation:
 theme:
   name: material
   language: en
+  # overrides/partials/source.html drops the mount point Material uses to fetch
+  # star counts from api.github.com on every page view. See the file for why.
+  custom_dir: overrides
+  # Material otherwise pulls Roboto from fonts.googleapis.com on every page,
+  # which makes every visitor's browser contact Google. This site must not load
+  # anything from a third party, so the system font stack is used instead.
+  # Do not set this to a font name: any value here reintroduces the request.
+  font: false
   features:
     - navigation.instant
     - navigation.tracking

overrides/partials/source.html

@@ -0,0 +1,21 @@
+{#-
+  Overrides the theme's partial of the same name.
+
+  The only change is that `data-md-component="source"` is gone. Material mounts
+  a component on that attribute which fetches https://api.github.com/repos/...
+  on every page view, to show star and fork counts next to the repository link.
+  This site must not make visitors' browsers contact a third party, so the mount
+  point is removed; the link and icon are unaffected, only the counts disappear.
+
+  Keep this file in step with the theme's version when upgrading
+  mkdocs-material - it is a copy, not an extension.
+-#}
+<a href="{{ config.repo_url }}" title="{{ lang.t('source') }}" class="md-source">
+  <div class="md-source__icon md-icon">
+    {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+    {% include ".icons/" ~ icon ~ ".svg" %}
+  </div>
+  <div class="md-source__repository">
+    {{ config.repo_name }}
+  </div>
+</a>

tools/hooks.py

@@ -12,6 +12,8 @@
    cannot silently leave a page with a dangling warning.
 4. Apply the same check to the `x-phyphox-inconsistency` keys in the OpenAPI
    description, so the spec and the to-do list cannot drift either.
+5. Fail the build if the generated site would make a visitor's browser fetch
+   anything from a third party.
 """
 
 import os
@@ -209,3 +211,71 @@ def _render_list():
             if e.get("issue"):
                 out.append(f"[Tracking issue]({e['issue']})\n")
     return "\n".join(out)
+
+
+# --------------------------------------------------------------------------
+# No third-party requests
+# --------------------------------------------------------------------------
+#
+# Visitors must be able to read this site without their browser contacting
+# anyone but the host serving it. That is easy to lose by accident: Material
+# pulls Roboto from fonts.googleapis.com unless `font: false` is set, mounts a
+# component that calls api.github.com when repo_url is present, and Swagger UI
+# ships a validator badge that posts the spec URL to validator.swagger.io. All
+# three are switched off - this check is what stops them coming back unnoticed
+# on the next dependency bump.
+#
+# Only *automatic* fetches count. Ordinary hyperlinks are fine; a visitor
+# choosing to follow one is not the site phoning home.
+
+_RESOURCE_TAG = re.compile(
+    r"<(link|script|img|iframe|source|video|audio|embed|object)\b([^>]*)>", re.I)
+_URL_ATTR = re.compile(r"(?:src|href|data)\s*=\s*[\"']([^\"']+)[\"']", re.I)
+_REL_ATTR = re.compile(r"rel\s*=\s*[\"']([^\"']+)[\"']", re.I)
+_CSS_URL = re.compile(r"(?:url\(\s*[\"']?|@import\s+[\"'])(https?:)?//([^)\"'\s]+)")
+
+# rel values that describe a relationship without fetching anything.
+_NON_FETCHING_RELS = {"canonical", "alternate", "author", "license", "me",
+                      "nofollow", "noopener", "noreferrer"}
+
+
+def _is_absolute(url):
+    return url.startswith(("http://", "https://", "//"))
+
+
+def on_post_build(config, **kwargs):
+    site_dir = config["site_dir"]
+    offenders = []
+
+    for root, _, files in os.walk(site_dir):
+        for fn in files:
+            path = os.path.join(root, fn)
+            rel_path = os.path.relpath(path, site_dir)
+            if fn.endswith((".html", ".htm")):
+                with open(path, encoding="utf-8", errors="ignore") as f:
+                    text = f.read()
+                for m in _RESOURCE_TAG.finditer(text):
+                    tag, attrs = m.group(1).lower(), m.group(2)
+                    url = _URL_ATTR.search(attrs)
+                    if not url or not _is_absolute(url.group(1)):
+                        continue
+                    rel = _REL_ATTR.search(attrs)
+                    rels = set((rel.group(1) if rel else "").lower().split())
+                    if rels & _NON_FETCHING_RELS:
+                        continue
+                    offenders.append(f"{rel_path}: <{tag}> {url.group(1)}")
+            elif fn.endswith(".css"):
+                with open(path, encoding="utf-8", errors="ignore") as f:
+                    text = f.read()
+                for m in _CSS_URL.finditer(text):
+                    offenders.append(f"{rel_path}: css url() //{m.group(2)}")
+
+    if offenders:
+        shown = "\n".join(f"  {o}" for o in sorted(set(offenders))[:20])
+        more = len(set(offenders)) - 20
+        raise ValueError(
+            "The built site would make visitors' browsers fetch from a third "
+            "party:\n" + shown
+            + (f"\n  ... and {more} more" if more > 0 else "")
+            + "\n\nEverything the site needs must be served from the site "
+              "itself. See the 'No third-party requests' note in tools/hooks.py.")