Github mermaid rendering is still broken in dark mode

[echlebek]

🏷️ Discussion Type

Bug

💬 Feature/Topic Area

UX/UI

Body

Previous discussion, which indicates unresolved issues, but maintainer asking for new issue to be filed: https://github.com/orgs/community/discussions/35733

While Github mermaid rendering now works when the theme is explicitly set to dark mode, it is still broken when dark mode is implied by system setting.

Given this mermaid source:

sequenceDiagram
  box transparent Reconciliation on Resource Event
    participant client as k8s-client
    participant api as api-server
    participant cr@{ "type": "control" } as controller-runtime
  end
  client->>api: spec subresource update
  api-->>client: ok
  api->>cr: resource event
  loop reconciler
    cr->>cr: compute status, can retry
  end
  cr->>api: status subresource apply
  api-->>cr: ok

Loading

It renders like this when the theme is set to system, and the system theme is dark mode: (MacOS Tahoe, Chrome 147)

Has been reproduced by a colleague also on Mac OS Tahoe and Chrome.

Other than attempting to exert very fine grained control over the diagram styling, there doesn't appear to be anything I can do to fix this as a user, unless I want to disable the sync with system mode.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[jovbcorreia]

Hi @echlebek! Can confirm this is a known issue — Mermaid on GitHub reads the theme at render time but doesn't correctly detect the prefers-color-scheme: dark media query when you're using the "System" sync option. It only works when the theme is explicitly set to Dark in GitHub settings.

Workaround while GitHub fixes this:

You can force Mermaid to use a dark-compatible theme directly in your diagram using the %%{init: ...}%% directive:

%%{init: {'theme': 'dark'}}%%
sequenceDiagram
  ...

This makes the diagram render with the dark theme regardless of what GitHub detects from the OS, so it looks correct for everyone in dark mode. The downside is it will always use dark theme even for light mode users, so it's a trade-off.

A better long-term workaround would be to use 'theme': 'neutral' which tends to render well in both light and dark backgrounds:

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
  ...

The root cause is that GitHub's Mermaid integration doesn't re-render diagrams when prefers-color-scheme changes, and the initial detection fails when using system sync. Worth upvoting the original discussion you linked so GitHub prioritises the fix.