Fix draft HIP diagram rendering and add dark-theme image backdrop - #1451
Merged
Merged
Conversation
Three related fixes for HIP diagrams on hips.hedera.com: 1. Draft HIP assets now resolve. The build was rewriting every `../assets/...` reference to `/assets/...`, but draft HIPs are fetched from open PR branches and their assets only exist there, not on `main`. Drafts now rewrite to a `raw.githubusercontent.com` URL pinned to the PR's commit SHA. GitHub serves commits from open PR forks via the upstream repo path, so this works for fork PRs too. 2. Missing draft assets show a friendly placeholder. Authors sometimes reference an `../assets/...` path but forget to commit the file (e.g. HIP-1424 references `Merkle proof sketches.png`, never committed). The build now cross-checks each image reference against the PR's actual file list and replaces missing ones with a dashed callout instead of showing a broken-image icon. 3. Dark-theme image backdrop. Most HIP diagrams are authored on white, so on the dark page they either disappeared (transparent PNGs) or floated as glaring white blocks. Wrap each `article img` in a soft off-white card with subtle border and shadow in dark mode only; light mode is untouched. Signed-off-by: Michael Garber <michael.garber@hashgraph.com>
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| Security | 1 high |
🟢 Metrics 0 duplication
Metric Results Duplication 0
TIP This summary will be updated as you push new changes. Give us feedback
RaphaelMessian
approved these changes
Apr 13, 2026
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
Three related fixes that make HIP diagrams render correctly on hips.hedera.com.
1. Draft HIP assets now resolve
site/scripts/build-data.jswas rewriting every../assets/...reference to/assets/..., which Vite serves frompublic/assets/. That directory is populated only frommain's checked-in assets, so any draft HIP fetched from an open PR branch had its diagrams 404. HIP-1424 (8 images) and HIP-1427 (5 images) were both affected — the issue was zero diagrams visible on either draft HIP page.Draft bodies now rewrite to a
raw.githubusercontent.comURL pinned to the PR'sheadRefOid. GitHub serves commits from open PR forks via the upstream repo path when addressed by commit SHA, so this works for fork-based PRs too (verified live against PR-1424 fromNana-EC/hiero-improvement-proposal). Merged HIPs continue to use/assets/.2. Missing draft assets show a friendly placeholder
Authors occasionally reference an
../assets/...path but forget to commit the file. HIP-1424 is a current example: it referencesassets/hip-1424/Merkle proof sketches.pngat line 441, but that file is not in the PR's file list. There is nothing the site can fetch.The build now cross-checks every image reference in a draft HIP against the PR's actual file list (already available in
_data/draft_hips.json). If the file is missing, the markdown image is replaced with a dashed callout instead of a broken-image icon. The check is generic, so any draft HIP that ships with an uncommitted asset reference gets the same treatment.3. Dark-theme image backdrop
Most HIP diagrams are authored on white. On the dark page they either disappeared (transparent PNGs) or floated as glaring white blocks.
[data-theme=\"dark\"] article imgnow gets a soft off-white background, padding, subtle border, and drop shadow so diagrams read as embedded artwork. Light mode is untouched.Audit context
I scanned every
<img>andreference across all 155 merged HIPs and all 13 open draft PRs while diagnosing the original report. After this PR the only outstanding broken references are upstream content gaps that need author action, not site fixes:HIP/hip-551.md:119) — referencesassets/hip-551/record-stream.png, never committed tomain. Author needs to commit the file or remove the line.assets/hip-1424/Merkle proof sketches.png, not in the PR. Author needs to add the file. With this PR the page no longer shows a broken-image icon for it.Files changed
site/scripts/build-data.js—replaceHipImagesacceptsrawBaseandavailableAssets; draft HIP build path passes both.site/src/style.css—[data-theme=\"dark\"] article imgcard styling and.missing-diagramcallout style.Test plan
npm run build:data && npm run buildfromsite/) — succeeds, 167 HIPs built.dist/data/hip-bodies.*.jsonresolve200againstraw.githubusercontent.comfor HIP-1424 (7/8 — the 8th is the missing-asset case) and HIP-1427 (5/5).Merkle proof sketches.png.