Only generate responsive image variants for images that use them

[borland]

How to review this PR

Go commit by commit and skip commit 2; there's too many files otherwise

• Commit 1 is the change to the img.mjs script, so it only generates responsive images for things referenced by :img{ and bannerImage: frontmatter
• Commit 2 is the cleanup, which deletes about 9,800 files. This isn't realistic to review, so I had claude programatically write a python script to verify that the commit only contains deletions of generated images, which it does.
• Commit 3 is me just testing that I can add a new responsive image and it works. I changed the main page to use :img{ as there is significant benefit for the index page that everyone starts with - it contains two images, both of which are larger than they should be

Before

After

Reducing risk

I tested this both locally and on the staging site. All you need to do is browse to pages with images. The main /docs page now uses responsive images to prove that path, and basically any other page has a raw PNG in it

---

Claude's notes

The problem

public/docs/i/ holds 600/1000/2000px WebP variants plus an x/ fallback for every image in public/docs/img/ — 7,905 files, 335 MB, all committed to the repo and all uploaded to blob storage on every deploy.

Almost none of it is ever requested. The only code that emits /docs/i/ URLs is getImageInfo in custom-markdown.mjs, and it only runs for two things: the :img{} remark directive and bannerImage frontmatter. Across 1,267 content pages, exactly one page (/docs/projects/badges) uses :img{}. Everything else writes plain ![](/docs/img/…) markdown, which serves the original straight out of /docs/img/.

So 7,905 committed binaries exist to serve two images.

I found this by grepping the built package: of 2,697 HTML files, 2 reference /docs/i/ at all.

The tree had also gone stale, because img.mjs only ever added files, never removed them. i/x/blueprint.png was still there long after its source image was deleted — and the site's own index page still pointed at it.

The fix

Rewrite src/themes/octopus/utilities/img.mjs to scan src/**/*.{md,mdx,astro} for the paths getImageInfo actually receives, generate variants only for those, and prune anything that no longer belongs.

That makes the tree self-maintaining: removing the last :img{} reference to an image now removes its generated output on the next npm run dev, and adding one generates just what that image needs. public/docs/i/ goes from 7,905 files to 8.

Three smaller things fall out of it:

• 1,971 .json metadata sidecars dropped. These are build-time inputs — getImageInfo reads them out of public/ to emit width/height and cap the srcset widths — but because they live under public/ they were also copied into the deployed package and uploaded, where nothing ever fetches them.
• The updated timestamp is gone from the sidecars. Its only reader is dist-thinner.mjs, which is not wired into the build and never runs; without the field it simply finds nothing to do. (dist-thinner is deleted on the housekeeping branch, which is independent of this one.)
• The dead bannerImage in src/pages/index.md is removed. It pointed at /docs/img/blueprint.png, which no longer exists, so it produced a broken itemprop="image" — and it was the sole reason a stale variant survived.

I also fixed a latent bug in the generator while rewriting it: the original never awaited its sharp(...).toFile() calls, so writes raced against the process exiting.

Why remove rather than expand

Responsive images are worth having, and the honest alternative is to make every markdown image go through the pipeline — the win there would be large, since /docs/img/ is 214 MB of unresized PNGs. But that is a content-and-rendering change affecting 1,267 pages, not a build cleanup, and it should be its own decision.

What is not defensible is the status quo: paying 335 MB of repo weight and deploy time to serve two images, with no mechanism to keep it in sync. This PR makes the cost match the usage. If we later decide to apply :img{} broadly, the generator now scales to it correctly instead of brute-forcing every file in the tree.

Note that the variants must stay committed: astro build does not run img.mjs (only npm run dev does), so CI copies whatever is in public/. At 8 files that is fine.

Verification

Package size on this branch alone: 758.9 MB / 15,887 files → 483 MB / 6,020 files.

check	result
asset references resolved against files on disk	20,298 checked, 1 missing — see below
npm run crawl (linkinator)	5,472 links, 0 broken
npx playwright test	99 passed, 0 failed
astro build	clean, 2,697 pages

The one missing reference is /docs/img/icon-example.svg from components.mdx. It is absent from main and from the previously built package too, so it is pre-existing and unrelated — and components.mdx is an internal-only page that the housekeeping branch stops publishing anyway.

I confirmed /docs/projects/badges still renders correctly: the <img> keeps its srcset with all three widths, its x/ fallback, and the width/height attributes derived from the metadata sidecar.

Review notes

• The diff is 9,870 files, but 9,868 of them are deletions of generated binaries. The reviewable change is src/themes/octopus/utilities/img.mjs plus three frontmatter lines in src/pages/index.md.
• This branch is independent of Stop shipping build output that nothing can request #3280 (orion/housekeeping) and can merge in either order. The two overlap only in that housekeeping deletes 367 orphaned source images whose sidecars this branch also deletes; git resolves identical deletions without conflict, and img.mjs re-prunes on the next dev run regardless.

🤖 Generated with Claude Code

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3281.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[enf0rc3]

LGTM will be great for the lightbox component! https://github.com/OctopusDeploy/docs/pull/3313/changes#diff-9f9745786a41273d05896d7981bd762c8c33b441c55b0ddd97aa901ac6f9a464