Skip to content

docs: serve the badges ourselves instead of hot-linking them - #54

Merged
yesbert merged 2 commits into
mainfrom
docs/serve-the-badges-ourselves
Sep 3, 2026
Merged

docs: serve the badges ourselves instead of hot-linking them#54
yesbert merged 2 commits into
mainfrom
docs/serve-the-badges-ourselves

Conversation

@yesbert

@yesbert yesbert commented Sep 3, 2026

Copy link
Copy Markdown
Owner

What this changes

The badges on the landing page were the only externally fetched resources on the entire site — everything else (fonts, icons, diagrams, search index) is already local, and every other external URL is a link target that requests nothing until clicked. Serving them ourselves therefore does not merely shorten the privacy policy: until a visitor accepts the analytics notice, their browser now talks to nobody but this site's host.

  • Three badges committed under docs/assets/badges/ and referenced locally.
  • scripts/refresh-badges.sh regenerates them, taking the version from the newest dated section of CHANGELOG.md — the same source llms.txt uses, and for the same reason: VersionPrefix names the version being worked toward, which stays unreleased for the whole cycle.
  • LandingBadgeTests fails when the release badge and that changelog section drift apart, and when any documentation page loads an image from another host. The second test is the one that keeps the property from quietly eroding.
  • The privacy policy's Status badges from third parties section is replaced by a statement that there are none.

The CI badge is gone from the landing page, deliberately

It is the one badge whose entire value is being live: a frozen "passing" image is a claim about build status that can become false without anyone noticing. It stays in the README, where GitHub proxies images through its own camo service — so neither Shields.io nor GitHub's badge endpoint ever sees the reader there either.

The release badge names 4.0.3, which is not yet on nuget.org

That is the existing convention, not a new inconsistency: llms.txt already says 4.0.3, because AiIndexTests ties it to the newest dated changelog section rather than to what has been published. The window closes when the release gate is approved. The new test writes the same rule down for the badge, and it caught the mismatch on its first run.

How it was verified

  • Local gauntlet green (./scripts/local-gauntlet.sh)
  • docfx build --warningsAsErrors — 0 warnings, 0 errors
  • Enumerated every img/script/link with an absolute URL across the built site: none remain

Copilot AI lite review requested due to automatic review settings September 3, 2026 16:58

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The new tests have correctness gaps that can allow regressions to slip through without failing CI.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR removes externally hot-linked status badges from the DocFX landing page and serves equivalent badge SVGs from the repository, aiming to eliminate third-party requests before analytics consent is granted.

Changes:

  • Add locally committed badge SVGs under docs/assets/badges/ and update the landing page to reference them.
  • Add a script (scripts/refresh-badges.sh) to regenerate the badges based on the newest dated release section in CHANGELOG.md.
  • Add documentation tests to (1) ensure the NuGet badge version matches the newest dated changelog release and (2) prevent documentation pages from embedding externally hosted images.
File summaries
File Description
tests/Stratara.Documentation.Tests/LandingBadgeTests.cs Adds guards for “no external image hosts” and release badge version drift.
scripts/refresh-badges.sh Provides a repeatable way to refresh committed badge SVGs from Shields.io.
docs/legal/privacy.md Updates privacy policy wording to reflect removal of third-party status badge requests.
docs/index.md Switches landing-page badges from external URLs to local assets/badges/*.svg paths.
docs/assets/badges/nuget.svg Adds locally served NuGet version badge SVG.
docs/assets/badges/license-mit.svg Adds locally served license badge SVG.
docs/assets/badges/dotnet-10.svg Adds locally served .NET version badge SVG.
Review details
  • Files reviewed: 4/7 changed files
  • Comments generated: 2
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread tests/Stratara.Documentation.Tests/LandingBadgeTests.cs Outdated
Comment thread tests/Stratara.Documentation.Tests/LandingBadgeTests.cs Outdated
@yesbert
yesbert force-pushed the docs/serve-the-badges-ourselves branch from 65b0685 to 4421c66 Compare September 3, 2026 17:20
@yesbert
yesbert merged commit 121240c into main Sep 3, 2026
5 checks passed
@yesbert
yesbert deleted the docs/serve-the-badges-ourselves branch September 3, 2026 17:23
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.

2 participants