Skip to content

perf: deduplicate zh site_libs and images trees against root copies - #331

Merged
ShixiangWang merged 1 commit into
mainfrom
perf/zh-site-dedup
Oct 11, 2026
Merged

ShixiangWang merged 1 commit into
mainfrom
perf/zh-site-dedup

Conversation

@ShixiangWang

Copy link
Copy Markdown
Member

Summary

Resolves the A3.2 (zh 站点资源去重) item of #306: babelquarto copies the shared site_libs/ and images/ trees into the rendered zh/ tree as byte-identical duplicates of the root copies, adding ~94 MB to every deploy (measured on the live artifact from PR #330: zh/site_libs 51.6 MB + zh/images 42.7 MB, diff -rq → 0 differences).

Changes

New post-render pipeline step (both publish workflows)

  • .github/scripts/rewrite-zh-site-refs.py — resolution-based rewriter: for every zh HTML reference to site_libs/… or images/…, resolves it against the page directory; if the target lands inside zh/ and the root-tree equivalent exists, rewrites it to the root tree's relative path. Non-HTML files are untouched (verified: the only candidate, a dead leaflet.css inside zh/site_libs, is never linked by any page). References whose root counterpart is missing are left as-is and reported.
  • .github/scripts/prune-zh-duplicates.py — deletes zh/site_libs + zh/images, but aborts with a nonzero exit if any zh HTML still resolves a reference inside them. A missed rewrite fails the build loudly instead of shipping broken pages.
  • Wired into quarto-publish.yml and quarto-publish-update-cache.yml after the zh figure-refs rewrite, before lazy-loading and freeze-cache save.

Chunk-label drift fix (root cause of the only 5 broken zh figure refs)

  • Omics/ManhattanPlot.zh.qmd: fig-2.3Hlight → fig-2.3Highlight (matches English)
  • Omics/CellChatCirclePlot.zh.qmd: fig1-overall-circle/fig2-individual-circle/fig3-chord/fig4-heatmap → fig-1-overall-circle/fig-2-individual-circle/fig-3-chord/fig-4-heatmap, converted to the #| option style used repo-wide; dimensions preserved. No @fig- cross-references exist in these files (rename-safe).

Measured impact (on a copy of the live artifact)

Metric Before After Δ
Site total 377 MB 282 MB −95 MB
zh tree 147 MB 53 MB −94 MB

Validation

  • ✅ Rewrite on live-artifact copy: 5,215 refs across 267 pages, 0 unresolved — all resolve to existing root-tree files after pruning
  • ✅ Root site_libs/ and images/ bytes unchanged (hash-verified)
  • ✅ Prune guard: aborts (exit 1) when a stale ref is injected; idempotent on a clean run
  • ✅ Both workflows parse as valid YAML; scripts pass py_compile
  • ⏳ PR CI full render will validate end-to-end (freeze covers zh chunks; post-render scripts run fresh each build)

🤖 Generated with Claude Code

babelquarto copies the shared site_libs/ and images/ trees into the
rendered zh/ tree as byte-identical duplicates of the root copies,
adding ~94 MB (51.6 + 42.7 MB) to every deployed site - 34% of the
artifact after the iVolcano fix.

Changes (issue #306 A3.2):
- Add .github/scripts/rewrite-zh-site-refs.py: resolution-based
  rewriter.  Every zh HTML reference that resolves under zh/site_libs/
  or zh/images/ is rewritten to the root-tree equivalent relative to
  the page; references whose root target does not exist are left
  untouched and reported (measured on the live artifact: 5,215 refs
  across 267 pages, 0 unresolved).
- Add .github/scripts/prune-zh-duplicates.py: deletes the zh/site_libs
  and zh/images trees, but refuses (nonzero exit) if any zh HTML still
  resolves a reference inside them - so a missed rewrite fails the
  build loudly instead of shipping broken pages.
- Wire both scripts into quarto-publish.yml and
  quarto-publish-update-cache.yml after the zh figure-refs step.
- Fix 5 zh chunk labels that drifted from their English counterparts
  (the cause of the only 5 broken zh figure refs in the current site):
  ManhattanPlot.zh.qmd fig-2.3Hlight -> fig-2.3Highlight;
  CellChatCirclePlot.zh.qmd fig1-overall-circle -> fig-1-overall-circle
  and three siblings, converted to the #| option style used elsewhere.

Verified on a copy of the deployed artifact: rewrite + prune leaves 0
broken zh references (5,215/5,215 resolve to existing root-tree files),
root site_libs/ and images/ bytes unchanged, and the prune guard aborts
when a stale reference is injected.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

✅ QMD Format Check

No new QMD tutorial files to check.

Automated check by the PR Review workflow.
See contribution guidance for the expected tutorial format.

@github-actions

Copy link
Copy Markdown
Contributor

📊 Quarto Render Preview

The new or modified Quarto files have been rendered and are available as artifacts.

🔗 View and Download Rendered Files

Click the link above, scroll to the "Artifacts" section at the bottom of the page, and download quarto-rendered-files to preview the rendered HTML files.

Modified files:

Omics/CellChatCirclePlot.zh.qmd Omics/ManhattanPlot.zh.qmd

@ShixiangWang
ShixiangWang merged commit 4a0a811 into main Oct 11, 2026
5 checks passed
@ShixiangWang
ShixiangWang deleted the perf/zh-site-dedup branch October 11, 2026 18:05
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.

1 participant