Skip to content

Render guide badges locally instead of hotlinking shields - #288

Merged
tony merged 3 commits into
mainfrom
feat/local-guide-badges
Nov 9, 2026
Merged

tony merged 3 commits into
mainfrom
feat/local-guide-badges

Conversation

@tony

@tony tony commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Generated port guides hotlinked img.shields.io and GitHub Actions badges, so every reader's browser, every CI browser check, and every Markdown twin and llms export depended on a third party for images whose values the build already holds. This renders them at staging instead, with no network.

  • scripts/lib/badges.mjs, called from stagedPortGuides, maps each shields URL to a label, message and colour, takes versions from site/src/data/registry.json, renders the SVG with badge-maker@6.0.0 (pinned exactly), and writes content-hashed files to the gitignored site/public/badges/. The Markdown image points at that file. Staging runs before the twins and llms exports, so they carry the local URL too.
  • A badge with no mapping throws rather than hotlinks.
  • rehypeSiteRoot serves a port build's badges from its own mount (/ruby/latest/badges/<hash>.svg), so a port-only publication never depends on the root build having published the same hash. The Markdown twins and llms exports keep the root /badges/ path, because the root build restages every port and always has the file.
  • Version colour follows shields' own rule (first digit 0 or a pre-release word is orange, else blue), taken from services/color-formatters.js at server-2026-08-21 (commit 080e177a0a44). A registry version that already starts with v (Go) keeps it instead of rendering vv0.1.0.
  • stage-port-docs --check now compares badge files by name and bytes.
  • The README cached in site/src/data/example-sources.json holds four badge URLs, but only as quoted source text inside code fences, never as images, and no page excerpts them. Rewriting them would falsify the quote, so they stay verbatim. A new test scans site/src/content for off-origin badges.

Off-origin URLs: 23 to 0

Across the eight cached port guide sets, 23 off-origin badge URLs sit in the source guides. After staging there are 0 (findOffOriginBadges over every staged guide of every cached port, with negative controls in site/test/port-guide-badges.test.ts). A Ruby-only astro build holds src="/ruby/latest/badges/<hash>.svg", the 8 files in that build's badges/, and no img.shields.io, badge.svg, badge.fury or badgen.net string in any output file.

Rendering matches shields

badge-maker is shields' own renderer. Three static badges (license, docs, tmux version) and a gem/v badge came out byte-identical to the SVGs img.shields.io returns for the same URL (gem/v/rake compared at the version shields served that moment, 13.4.2).

Why CI status badges are dropped

An Actions badge shows a live pass or fail the build cannot know. A static "passing" would lie, so the badge is dropped together with its link, which led only to the workflow page.

Prior art

badge-maker 6.0.0 is MIT OR Apache-2.0, pinned exactly (gitHead 991ffcf in badges/shields), with anafanafo (MIT) and css-color-converter as its dependencies. A GitHub repo and code search found no remark or rehype plugin that localizes shields badges (astro-badge is a UI component). Astro's build-time remote image fetch needs network and was rejected for the no-network goal.

Related: #287 (the check guard).

Test plan

  • vitest: port-guide-badges, stage-port-docs, port-prose, prose-markdown, rehype-code-tabs, rehype-tmux-keys (6 files, 223 tests)
  • mutation check: the old colour and v rules fail 6 of the new tests
  • astro check: 0 errors, 0 warnings
  • oxlint over scripts, site/src/plugins and the new test: no warnings in the touched files (existing warnings elsewhere are unchanged)
  • Ruby-only astro build (858 pages): badges present under /ruby/latest/badges/, no shields or badge.svg URL in any file
  • stage-port-docs --cached --check passes clean and fails once a badge file is removed
  • CI test (run 42532785027, green at e02bc34, which keeps badge files out of page lists and the staging sandbox)

Do not merge before the publisher wave ends; docs main is frozen until about 20:15 CST.

tony added 3 commits November 8, 2026 16:33
why: Source guides hotlink img.shields.io and GitHub Actions badges, so
every reader's browser, and every CI browser check, waits on a third
party for images the build already has the values for. The Markdown
twins and the llms exports carried the same URLs.

what:
- Add badge-maker 6.0.0, pinned exactly, to render shields badges
- Map each shields URL to label, message and colour at staging, take
  registry versions from site/src/data/registry.json, and write
  content-hashed SVGs to the gitignored site/public/badges/
- Colour versions by shields' own rule (first digit 0 or a pre-release
  word is orange, else blue; server-2026-08-21, commit 080e177a0a44),
  and keep a leading v rather than doubling it
- Throw on a badge with no mapping rather than hotlink it
- Drop GitHub Actions status badges with their link: the build cannot
  know pass or fail, and a static "passing" would lie
- Make stage-port-docs --check compare badge files by name and bytes
- Test every cached port's staged guides for off-origin badges, with
  negative controls, and scan site/src/content for hand-written ones

The badges in the README cached in example-sources.json are quoted
source text inside code fences, never images, so they stay verbatim.
why: Badge SVGs are content-hashed files in site/public/badges/, and a
root-relative /badges/<hash>.svg is published only by the root build. A
port-only publication that mints a new hash would 404 its badges until
the root redeployed, though every shell already copies public/ into its
own mount.

what:
- Point a port build's guide badge images at <port root>/<port>/<version>/badges/
  in rehypeSiteRoot; a guide of another port, and a build with no
  port, keep the root path
- Test both mounts through the markdown processor

The Markdown twins and llms exports keep the root /badges/ path: the
root build restages every port, so the file is always there.
why: CI's test job failed on the badge branch in two places. The staging
publication tests copy a fixed list of scripts into a temp directory,
which lacked scripts/lib/badges.mjs and the registry data it read for
every guide, though only a version badge needs it. And the API-link
oracle took the badge SVGs that stagedPortGuides returns for pages and
reported them as pages with no route.

what:
- Read registry.json only when a version badge needs it
- Copy scripts/lib/badges.mjs into the staging publication fixtures
- Skip badges/ entries when api-destinations lists staged guide pages
@tony
tony merged commit 0f6a596 into main Nov 9, 2026
3 checks passed
@tony
tony temporarily deployed to docs-preview-cleanup November 9, 2026 13:38 — with GitHub Actions Inactive
tony added a commit that referenced this pull request Nov 9, 2026
…ts (#291)

why: Six ports had docs branches ready but no published site, and
three shared fixes were waiting behind them. Releasing them together
gives one docs commit to trust for deployment and one set of caller
pins to move, instead of six separate waves.

what:
- Add OCaml (#264), Haskell (#265), Erlang (#266, #278, #279, #280,
  #284, #292), Common Lisp (#268), Perl (#274) and Clojure (#276):
  native API pages, tested guides, navigation, landing and switcher
  entries, and cross-reference data for each
- Keep browser checks from loading third-party resources, and pass
  the check origin to the three scripts that named an undefined base
  (#287)
- Render guide badges at build time instead of hotlinking shields
  (#288)
- Size the reference sidebar and member bars from the viewport, so
  the Chrome iOS keyboard no longer shrinks them (#290)
- Make the OCaml model producer verify its native build inputs in
  their checkout and reject stale ones, with controls run in CI
- Offer one switcher page per port, and title Perl's workspace guide
  "Workspace guide"
- Regenerate the registry, mention index and cross-reference counts
  for the combined port set

Base main 2593131, head dabe59b. Port heads: #264 7d4f88f
and 73fb1ad, #265 dc024e3, #268 947da1f, #274 818fa2e,
#276 a134503, #287 a437e97, #292 e7740d9.

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — e02bc344 Deployed Nov 9, 2026 by tony via cleanup #223
docs-preview — e02bc344 Deployed Nov 9, 2026 by tony via publish-preview / publish #1324
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant