Add mermaid support - #13741
Add mermaid support#13741
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds support for rendering Mermaid diagrams from Markdown code blocks, introducing a custom Markdown block syntax, a node processor, and a client-side MermaidViewer component that dynamically loads the Mermaid library and handles theme updates. Feedback on the implementation highlights a security risk with using securityLevel: 'loose' (XSS), a bug where the diagram does not re-render when its content changes due to a missing didUpdateComponent implementation, an optimization opportunity to cache the imported module, and a potential CSP violation caused by using eval for dynamic imports.
|
I'm pretty far out of my element here using js interop and Jaspr, two things I'm only vaguely familiar with. I'd appreciate a thorough review @parlough ! |
|
Staged preview of the updated docs.flutter.dev site (updated for commit 82556a6): https://flutter-docs-prod--docs-pr13741-add-mermaid-support-ve3ntyr2.web.app |
|
Staged preview of the updated flutter.dev site (updated for commit 82556a6): https://flutter-dev-230821--www-pr13741-add-mermaid-support-fzptfisf.web.app |
|
As an alternative approach instead of using mermaid.js, we could use https://github.com/orestesgaolin/mermaid/tree/main/packages/mermaid_core to render the diagrams to SVGs at serve/build time. This is the demo https://roszkowski.dev/mermaid/ Seems like this is not published yet, but if we were to use it maybe we can convince @orestesgaolin to publish it :) |
I would much rather use this, I'll try it out |
|
Would you like me to publish mermaid to pub.dev? For now I only published katex https://pub.dev/packages/katex With mermaid I found that it sometimes does not well represent elk layouts and there are slight differences in rendering |
I'm not concerned with those small rendering differences. I have noticed one bug, the arrow label renders in the wrong spot when the flowchart is 
If you plan on maintaining this library, we'd likely want to use it over the JSInterop solution (and we can find a way to contribute and help out). But if you don't plan on maintaining, thats okay, no pressure. |
parlough
left a comment
parlough
left a comment
There was a problem hiding this comment.
Thanks for exploring this @ericwindmill! It's exciting. Looks pretty good already, just some questions and comments, primarily about if we can move the rendering to the build?
There was a problem hiding this comment.
Thanks for making those updates @ericwindmill!
Seems we need some upstream fixes, but I'm fine with landing this and iterating upstream and here.
Seemingly upstream issues:
- SVG part IDs for aren't unique or namespaced for each diagram, causing overlap.
- Seems there's no consistent classes for configuring global styling.
- In the light mode version, there's a white background generated that visually conflicts with the background of the container.
keep the issues coming, we'll make sure to bring full parity to mermaid.js |
Updates `site_shared` from `mermaid_core ^0.1.2` to `^0.3.0`, following the integration in #13741. --- This includes the published diagram configuration, CSS color, and layout fixes, with ELK 0.2.0 resolved transitively. The existing server-rendered light/dark SVG integration requires no API changes. Release notes: https://github.com/orestesgaolin/mermaid/releases/tag/mermaid-v0.3.0 Validation with Dart 3.14.0-173.0.dev: - Dependency resolution uses hosted `mermaid_core 0.3.0` and `elk 0.2.0`. - Analysis of `site_shared`, `sites/docs`, and `sites/www` passes. - All 75 existing `sites/www` tests pass. - The actual `MermaidDiagram` component renders the current documentation example in both themes, preserves its `classDef` color, and preserves escaped source fallback for malformed input. - The documentation page was served locally and visually inspected in both themes. - Full docs static generation passes: all 1,424 routes generated. An isolated copy of Jaspr CLI 0.23.4 changed only its hard-coded proxy port from 5567 to 5577 to avoid an unrelated local server; the shared CLI and website source were unchanged. Build options match the standard docs build. The generated Markdown documentation page was inspected in both themes, with two SVG variants and no fallback.
5 participants
Description of what this PR is changing or adding, and why:
Adds Mermaid diagram support. "Yeehaw" for code and version control instead of saving diagrams as images.
Presubmit checklist
of 80 characters or fewer.