Repository navigation
Render guide badges locally instead of hotlinking shields - #288
Merged
Merged
Conversation
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
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 was referenced Nov 9, 2026
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Generated port guides hotlinked
img.shields.ioand 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 fromstagedPortGuides, maps each shields URL to a label, message and colour, takes versions fromsite/src/data/registry.json, renders the SVG withbadge-maker@6.0.0(pinned exactly), and writes content-hashed files to the gitignoredsite/public/badges/. The Markdown image points at that file. Staging runs before the twins and llms exports, so they carry the local URL too.rehypeSiteRootserves 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.services/color-formatters.jsatserver-2026-08-21(commit 080e177a0a44). A registry version that already starts withv(Go) keeps it instead of renderingvv0.1.0.stage-port-docs --checknow compares badge files by name and bytes.site/src/data/example-sources.jsonholds 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 scanssite/src/contentfor 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 (
findOffOriginBadgesover every staged guide of every cached port, with negative controls insite/test/port-guide-badges.test.ts). A Ruby-only astro build holdssrc="/ruby/latest/badges/<hash>.svg", the 8 files in that build'sbadges/, and noimg.shields.io,badge.svg,badge.furyorbadgen.netstring in any output file.Rendering matches shields
badge-makeris shields' own renderer. Three static badges (license, docs, tmux version) and agem/vbadge came out byte-identical to the SVGsimg.shields.ioreturns for the same URL (gem/v/rakecompared 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-maker6.0.0 is MIT OR Apache-2.0, pinned exactly (gitHead 991ffcf in badges/shields), withanafanafo(MIT) andcss-color-converteras its dependencies. A GitHub repo and code search found no remark or rehype plugin that localizes shields badges (astro-badgeis 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
vrules fail 6 of the new testsastro check: 0 errors, 0 warningsscripts,site/src/pluginsand the new test: no warnings in the touched files (existing warnings elsewhere are unchanged)/ruby/latest/badges/, no shields orbadge.svgURL in any filestage-port-docs --cached --checkpasses clean and fails once a badge file is removedtest(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.