Fix blog mermaid diagrams: blank-render race + mobile legibility#5283
Merged
Conversation
The mermaid shortcode set startOnLoad:true, but mermaid v10's ESM build wires rendering to window's "load" event at import time. Because the shortcode imports mermaid dynamically from a CDN, that listener only fires when the module is still in-flight at load -- on a cache hit, bfcache restore, or non-Chromium browser the event has already fired and the diagram silently stays blank. Switch to startOnLoad:false + an explicit mermaid.run(), which renders every .mermaid block regardless of load-event timing. Also inject a one-time responsive style (overflow-x:auto, svg max-width:100%) so a diagram never pushes the page wider than the viewport. Separately, the wide "flowchart LR" diagrams shrank to an illegible smudge on phones. Convert them to "flowchart TD" so each node is full-width and readable on mobile: developer-workflow-debug-and-junit (x2), native-linux-apple-watch-game-builder-crash-protection, and java-to-a-native-linux-app. The already-vertical TD chart and the sequence diagram are left unchanged. Verified by rebuilding with Hugo and rendering every diagram over HTTP at 390px and 1100px: all render, no page overflow, legible on mobile. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Blog prose gate✅ No net-new prose findings introduced by this PR. |
Contributor
Cloudflare Preview
|
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
2 participants
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.
Problem
Mermaid diagrams in the blog were broken in two ways (reported via
java-to-a-native-linux-app):mermaid.htmlshortcode usedstartOnLoad: true. Mermaid v10's ESM build wires rendering to thewindowloadevent at import time, but the shortcode imports mermaid dynamically from a CDN — so the listener only catchesloadwhen the module happens to still be in-flight. On a cache hit, a bfcache restore, or a non-Chromium browser,loadhas already fired and the diagram silently stays blank.flowchart LRdiagrams to fit the viewport, collapsing them into an unreadable smudge on phones.Fix
layouts/shortcodes/mermaid.htmlstartOnLoad: false+ an explicitmermaid.run()— renders every.mermaidblock regardless of load-event timing.<style>(overflow-x:auto,svg { max-width:100%; height:auto }) so a diagram never forces the page wider than the viewport.Converted wide
flowchart LR→flowchart TDso nodes stack full-width and stay legible on phones:developer-workflow-debug-and-junit.md(×2)native-linux-apple-watch-game-builder-crash-protection.mdjava-to-a-native-linux-app.mdThe already-vertical
TDchart (native-apple-watch-and-wear.md) and thesequenceDiagram(seamless-crash-protection.md) are unchanged.Verification
Rebuilt with Hugo and rendered every diagram over HTTP (real theme) at 390px and 1100px:
data-processed=true), no syntax errors.Content/theme only — no Java or prose-gate surface touched.
🤖 Generated with Claude Code