Skip to content

Fix draft HIP diagram rendering and add dark-theme image backdrop - #1451

Merged
mgarbs merged 1 commit into
hiero-ledger:mainfrom
mgarbs:fix/draft-hip-diagram-rendering
Apr 13, 2026
Merged

Fix draft HIP diagram rendering and add dark-theme image backdrop#1451
mgarbs merged 1 commit into
hiero-ledger:mainfrom
mgarbs:fix/draft-hip-diagram-rendering

Conversation

@mgarbs

@mgarbs mgarbs commented Apr 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Three related fixes that make HIP diagrams render correctly on hips.hedera.com.

1. Draft HIP assets now resolve

site/scripts/build-data.js was rewriting every ../assets/... reference to /assets/..., which Vite serves from public/assets/. That directory is populated only from main'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.com URL pinned to the PR's headRefOid. 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 from Nana-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 references assets/hip-1424/Merkle proof sketches.png at 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 img now 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> and ![](…) reference 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-551 (HIP/hip-551.md:119) — references assets/hip-551/record-stream.png, never committed to main. Author needs to commit the file or remove the line.
  • HIP-1424 (PR-1424) — references 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.jsreplaceHipImages accepts rawBase and availableAssets; draft HIP build path passes both.
  • site/src/style.css[data-theme=\"dark\"] article img card styling and .missing-diagram callout style.

Test plan

  • Local build (npm run build:data && npm run build from site/) — succeeds, 167 HIPs built.
  • Verified rewritten draft URLs in dist/data/hip-bodies.*.json resolve 200 against raw.githubusercontent.com for HIP-1424 (7/8 — the 8th is the missing-asset case) and HIP-1427 (5/5).
  • Verified missing-asset placeholder is injected into the built body for HIP-1424's Merkle proof sketches.png.
  • Deployed the build to a fork's GitHub Pages and visually verified on https://mgarbs.github.io/hiero-improvement-proposals/#hip-1424 in both light and dark themes.
  • Reviewer to confirm light-theme diagrams are unchanged on a few existing HIPs (HIP-1056, HIP-1340, HIP-1081).

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>
@mgarbs
mgarbs requested a review from a team as a code owner April 13, 2026 12:47
@codacy-production

Copy link
Copy Markdown

Not up to standards ⛔

🔴 Issues 1 high

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category Results
Security 1 high

View in Codacy

🟢 Metrics 0 duplication

Metric Results
Duplication 0

View in Codacy

TIP This summary will be updated as you push new changes. Give us feedback

@mgarbs
mgarbs merged commit c512ac6 into hiero-ledger:main Apr 13, 2026
4 of 9 checks passed
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