docs: mermaid diagrams follow the hexdocs light/dark theme - #91
Merged
Conversation
Closes#42. ex_doc marks dark mode by toggling `dark` on <body> (its stylesheet is written against `body.dark`). Reading that class rather than prefers-color-scheme covers all three of ex_doc's settings — light, dark and system — because ex_doc re-toggles the class itself when the OS scheme changes under "system". Three things the naive version gets wrong, all handled here: - The old code replaced each <pre> with the rendered SVG, discarding the diagram source. A theme switch then has nothing to re-render from, so the source is captured up front. - mermaid.render is async, so a fast light→dark→light toggle can land results out of order and leave the diagram on the wrong theme. Each pass is stamped and stale results are dropped. - <body>'s class list also churns for search focus and sticky scroll, so a bare MutationObserver would re-render diagrams on unrelated DOM activity. Only an actual change in dark-ness triggers a re-render. Supersedes the approach in #35 (closed by its author, "maybe is better other approach"), which forced the dark theme unconditionally and so broke light mode. That PR also reported diagrams not rendering at all; that half is already fixed on master — the generated markup is <pre><code class="mermaid"> and the existing selector matches it. Verified in a real browser against the built docs, not just by eye: light renders (#333 text fill), toggling body.dark re-renders on pass 2 (#ccc), toggling back re-renders on pass 3 (#333), and adding search-focused / scroll-sticky does NOT re-render. No orphan mermaid error divs after three passes, so no failed renders or leaks. Note this only reaches hexdocs.pm via a published release — doc changes without a version bump never ship. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Closes#42 (@clsource).
ex_doc marks dark mode by toggling
darkon<body>— its stylesheet is written againstbody.dark. Reading that class rather thanprefers-color-schemecovers all three of ex_doc's settings (light, dark, and system), because ex_doc re-toggles the class itself when the OS scheme changes under "system".Three things the naive version gets wrong
<pre>with the rendered SVG, so a theme switch had nothing to re-render from. Source is now captured up front.mermaid.renderis async, so a fast light→dark→light toggle can land results out of order and strand the diagram on the wrong theme. Each pass is stamped; stale results are dropped.<body>class churn. ex_doc also togglessearch-focusedandscroll-stickythere, so a bareMutationObserverwould re-render diagrams on unrelated DOM activity. Only an actual change in dark-ness triggers a re-render.Relationship to #35
Supersedes it. #35 was closed by its own author ("maybe is better other approach") — it forced the dark theme unconditionally, which breaks light mode. #35 also reported diagrams not rendering at all; that half is already fixed on master — generated markup is
<pre><code class="mermaid">and the existing selector matches it, confirmed in the built docs.Verification
Done in a real browser against the built docs, not by eye:
#333, no leftoverpre code.mermaidbody.dark#ccc#333search-focused+scroll-stickyNo orphan mermaid error divs after three passes, so no failed renders or leaks.
mix format,mix credo --strictclean.One caveat
This only reaches hexdocs.pm via a published release — doc-only changes without a version bump never ship, per
RELEASE.md. Merging this alone won't fix the live docs; it needs to ride a release. I have not bumped the version.🤖 Generated with Claude Code