docs: activate mermaid dark theme for hexdocs - #35
Closed
clsource wants to merge 3 commits into
Closed
Conversation
ContributorAuthor
This PR solves two problems in Hexdocs
 This is due to the odd code used for triggering renders.
 The current white theme does not look good in hexdocs dark mode.  |
clsource
commented
Jun 5, 2026
ContributorAuthor
maybe is better other approach |
GenericJam added a commit
that referenced
this pull request
Aug 30, 2026
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>
GenericJam added a commit
that referenced
this pull request
Sep 1, 2026
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>
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.
Improved hexdocs rendering