fix: remove third-party cdns

The theme and its defaults were pulling several
assets off-origin:

- Zensical 0.0.35 added a GLightbox extension that lazy-loads
  glightbox.min.js and glightbox.min.css from unpkg.com whenever
  window.GLightbox is undefined (pp() in the theme bundle).
- The theme unconditionally injects a <link> to fonts.googleapis.com
  and a preconnect to fonts.gstatic.com when [project.theme].font is
  not disabled.
- CI ran `pip install zensical` unpinned, so upgrades like 0.0.34 to
  0.0.35 silently introduced new off-origin loads without a review
  signal.

Changes:

- Add scripts/vendor_glightbox.py and scripts/vendor_glightbox.toml,
  mirroring the existing Mermaid vendoring. The script downloads the
  pinned glightbox build from cdn.jsdelivr.net and verifies SHA-256
  for both the JS and CSS.
- Vendor glightbox@3.3.1 into docs/assets/javascripts/glightbox.min.js
  and docs/assets/stylesheets/glightbox.min.css. Loading the UMD via
  extra_javascript defines window.GLightbox before the theme checks
  for it, short-circuiting the unpkg fetch. The CSS ships via
  extra_css.
- Disable the theme's default Google Fonts by setting `font = false`
  in [project.theme]. The site falls back to the system font stack
  already wired into the theme CSS.
- Pin zensical==0.0.40 in .github/workflows/docs.yml with a comment
  warning reviewers to audit for new unbundled js/css before bumping.
- Extend .gitattributes so docs/assets/stylesheets/** is binary,
  symmetric with the existing docs/assets/javascripts/** rule.
- Add a "Verify vendored GLightbox" step to the docs workflow so
  drift between the committed files and the pinned SHA-256 values
  fails CI.
- Document the new vendored dependency and its upgrade procedure in
  CONTRIBUTING.md, next to the existing Mermaid entry.

Author: yaythomas

.gitattributes

@@ -1,3 +1,4 @@
-# Vendored third-party JavaScript under docs/assets/javascripts/ is treated
-# as binary so PR diffs stay readable. See CONTRIBUTING.md for the convention.
+# Vendored third-party assets under docs/assets/ are treated as binary so
+# PR diffs stay readable. See CONTRIBUTING.md for the convention.
 docs/assets/javascripts/** binary
+docs/assets/stylesheets/** binary

.github/workflows/docs.yml

@@ -26,10 +26,14 @@ jobs:
           python-version: 3.x
 
       - name: Install dependencies
-        run: pip install zensical
+        # don't bump this without checking if there are new unbundled js/css in the theme
+        run: pip install zensical==0.0.40
 
       - name: Verify vendored Mermaid
         run: python3 scripts/vendor_mermaid.py --check
+
+      - name: Verify vendored GLightbox
+        run: python3 scripts/vendor_glightbox.py --check
 
       - name: Build documentation
         run: zensical build --clean

CONTRIBUTING.md

@@ -24,14 +24,21 @@ zensical build --clean
 
 ## Vendored dependencies
 
-The file `docs/assets/javascripts/mermaid.tiny.js` is a pinned copy of the
-`@mermaid-js/tiny` UMD build. We self-host it because the Content Security
-Policy on `docs.aws.amazon.com` blocks Zensical's default CDN load of Mermaid
-from `unpkg.com`.
+The Zensical theme lazy-loads a few third-party assets (Mermaid for diagrams,
+GLightbox for image zoom) from `unpkg.com` by default.
 
-Mermaid's tiny build supports flowcharts and sequence, state, class, and
-entity-relationship diagrams. It does not support mindmap or architecture
-diagrams, or KaTeX math rendering.
+For the Content Security Policy on `docs.aws.amazon.com`, we self-host pinned
+copies under `docs/assets/`. Each vendored asset exposes a `window.*` global
+(`window.mermaid`, `window.GLightbox`) that the theme's lazy-loaders check
+before hitting the CDN, so preloading our local copy short-circuits the
+unpkg fetch.
+
+### Mermaid
+
+`docs/assets/javascripts/mermaid.tiny.js` is a pinned copy of the
+`@mermaid-js/tiny` UMD build. The tiny build supports flowcharts and
+sequence, state, class, and entity-relationship diagrams. It does not
+support mindmap or architecture diagrams, or KaTeX math rendering.
 
 Upgrade procedure:
 
@@ -51,23 +58,63 @@ zensical serve
 #    together in the same commit.
 ```
 
-CI verifies the committed file matches the pinned SHA-256. If you hand-edit the
-vendored file or forget to update the SHA on upgrade, the build fails.
+### GLightbox
 
-### Directory convention
+`docs/assets/javascripts/glightbox.min.js` and
+`docs/assets/stylesheets/glightbox.min.css` are pinned copies of the
+`glightbox` npm package. Zensical's GLightbox Markdown extension wraps
+images in `<a class="glightbox">` and, when a user opens one, calls a
+lazy-loader that pulls the JS and CSS from unpkg unless
+`window.GLightbox` is already defined. We register the vendored copies
+via `extra_javascript` and `extra_css` in `zensical.toml` so the
+lazy-loader short-circuits and no unpkg request is made.
+
+Upgrade procedure:
+
+```bash
+# 1. Show the pinned version and the latest on npm
+python3 scripts/vendor_glightbox.py --latest
+
+# 2. Edit scripts/vendor_glightbox.toml. Bump `version`. Run the script.
+#    It will fail and print the new SHA-256s for both files. Paste those
+#    values into `sha256_js` and `sha256_css` in the TOML, then re-run.
+python3 scripts/vendor_glightbox.py
 
-JavaScript under `docs/` is split by ownership:
+# 3. Preview locally and open a page with an image. Click the image: the
+#    lightbox should open and DevTools Network should show no unpkg.com
+#    requests.
+zensical serve
 
-- `docs/assets/javascripts/` holds vendored third-party bundles. Treat these
-  as read-only outputs of the vendoring scripts under `scripts/`. Do not
-  hand-edit them. Upgrade by bumping the version pin in the corresponding
-  script and re-running it. Files in this directory are marked `binary` in
-  `.gitattributes` so PR diffs do not try to render minified code.
-- `docs/javascripts/` holds first-party scripts we author and maintain, such
-  as `mermaid-init.js`, which initializes the vendored Mermaid build.
+# 4. Commit scripts/vendor_glightbox.toml together with
+#    docs/assets/javascripts/glightbox.min.js and
+#    docs/assets/stylesheets/glightbox.min.css.
+```
+
+CI verifies the committed files match the pinned SHA-256 values for both
+Mermaid and GLightbox. If you hand-edit a vendored file or forget to update
+the SHA on upgrade, the build fails.
+
+### Directory convention
 
-Both directories are served from the same origin and register through
-`extra_javascript` in `zensical.toml`.
+Vendored third-party assets live under `docs/assets/` and are owned by the
+scripts under `scripts/`:
+
+- `docs/assets/javascripts/` holds vendored JS (`mermaid.tiny.js`,
+  `glightbox.min.js`).
+- `docs/assets/stylesheets/` holds vendored CSS alongside our own
+  `extra.css`. The vendored `glightbox.min.css` lives here.
+
+Treat all vendored files as read-only outputs of the vendoring scripts.
+Do not hand-edit them. Upgrade by bumping the version pin in the
+corresponding script's TOML and re-running the script. Vendored files are
+marked `binary` in `.gitattributes` so PR diffs do not try to render
+minified code.
+
+First-party scripts we author and maintain live under `docs/javascripts/`,
+for example `mermaid-init.js`, which initializes the vendored Mermaid
+build. Both `docs/assets/javascripts/` and `docs/javascripts/` are served
+from the same origin and register through `extra_javascript` in
+`zensical.toml`.
 
 ## Formatting