Repository navigation
ux: improve Mermaid rendering and theme switching - #26304
Merged
Merged
Conversation
Hide diagram source until the SVG is ready, re-render on light/dark theme changes, and avoid stale renders overwriting a newer theme. Co-authored-by: Cursor <cursoragent@cursor.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dvdksn
reviewed
Oct 8, 2026
| /* Mermaid blocks hold the diagram source until mermaid.js replaces it with | ||
| an SVG. Hide the source while that happens, unless rendering failed. */ | ||
| pre.mermaid:not(:has(svg)):not([data-error]) { | ||
| display: none; |
Contributor
There was a problem hiding this comment.
This rule loses to the Mermaid block’s flex utility because Tailwind’s utilities layer takes precedence over components, regardless of selector specificity.
I reproduced this in Chromium by blocking mermaid.js in the preview: the raw source remains visible with computed display: flex. Moving this rule outside the cascade layers changes it to display: none.
Could you move the rule outside @layer components and verify with Mermaid’s script delayed?
Generated by Codex
Contributor
Author
There was a problem hiding this comment.
The rule hid pre.mermaid until an SVG was present, but it sat inside @layer components while the element carries Tailwind's flex utility. Cascade layers rank utilities above components regardless of selector specificity, so the source stayed visible with display: flex. Unlayered styles win over every layer, so the rule now lives outside the layer block. Co-authored-by: Cursor <cursoragent@cursor.com>
dvdksn
approved these changes
Oct 8, 2026
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.
Summary
Problem: Mermaid diagrams briefly showed their raw source before the SVG appeared, stayed on the wrong palette after a light/dark theme toggle, and could leave Mermaid's error graphic in the page when a diagram failed to parse.
Why this change: Diagrams are used more often in the docs, so the renderer needs to match the site theme and avoid flashing source text while SVGs load.
Solution: Replace
mermaid.run()with a controlledmermaid.render()loop that caches each block's source, skips stale async results, re-renders when the<html>dark class changes, suppresses Mermaid's default error SVG, and hidespre.mermaiduntil an SVG is present (or a render error setsdata-errorso the source can still be inspected).@netlify /get-started/docker-concepts/the-basics/what-is-a-registry/
Preview: https://deploy-preview-26304--docsdocker.netlify.app/get-started/docker-concepts/the-basics/what-is-a-registry/
Example of pre-fix behavior: https://deploy-preview-26283--docsdocker.netlify.app/accounts/organization/
Generated by Cursor