docs: render card previews from one line of markdown, and lazy-load them

[marcalexiei]

Note

Just a POC, marking as draft until #515 and #516 are merged.

• Adds apps/frontend/src/plugins/rehypeCardImages.ts:
  a /api image that names no theme is emitted twice, once per site theme — light_github / dark_github or the *_repocard pair.
  One that names a theme is left untouched.
• Every /api image also gets loading="lazy" decoding="async",
  so the theme is not using costs no request.
• Drops the inline <img>/<a> HTML from docs/index.md and customization/theming.md;
  previews on the other docs pages became theme-aware without being edited.
  Once the other docs PRs are merged I'll rebase and apply the same change everywhere.

[vercel]

@marcalexiei is attempting to deploy a commit to the martin-mfg's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
github-stats-extended-backend	Ready	Preview	Aug 27, 2026 7:50pm

[martin-mfg]

• Could you please automatically link the images as described in #515 (comment)?
• What's the motivation behind loading="lazy" decoding="async"? Saving PAT and Vercel resources after deployment, or saving PAT resources locally during development? The former doesn't really matter because the images will be in server-side cache. If the latter is a concern (I have no idea how much of the hourly PAT limits a side load costs locally), can we restrict the lazy-loading to only apply locally please? I'd like the user experience in the deployed docs to be as smooth as possible, with less waiting for images to load and popping in suddenly.

[marcalexiei]

Could you please automatically link the images as described in #515 (comment)?

Now each preview links to its own URL, theme included, unless the markdown already links it somewhere else.

What's the motivation behind loading="lazy" decoding="async"?

decoding="async" is dropped, I thought it was a nice addition.

loading="lazy" is what stops a browser downloading both themes:
the copy that does not match the site theme is display: none, so it has no layout box and is never fetched.
e2e/docs-card-previews.spec.ts asserts exactly that.
Without it every browser pays for two images per card instead of one.
It helps long pages too, separately from the pairs: Available Themes is 152 single cards, and eagerly they all go out at once.

It also costs nothing in smoothness: loading="lazy" does not defer images at or near the viewport, so cards above the fold load immediately either way.
Only what is off-screen, or hidden by the theme, waits.

[martin-mfg]

loading="lazy" is what stops a browser downloading both themes

Oh, I didn't realize this.