Render diagrams using non-browser-based rendering libraries

[ghost]

The following diagram renders fine in Firefox:

The diagram does not render correctly using the following programs and libraries:

• Adobe FrameMaker 2020
• Apache Batik
• EchoSVG
• svgSalamander
• resvg
• rsvg-convert
• svglib
• prawn-svg
• CairoSVG
• ConTeXt
• QtSVG
• MS Word
• PlutoSVG

Many applications rely on those libraries for rendering SVG diagrams. For example, my text editor KeenWrite uses Kroki to generate mermaid SVG documents. These documents are then parsed by EchoSVG to render as PNG images in FlyingSaucer.

In the following image, the rendered SVG output is shown at the right:

Other SVG producers, such as Graphviz, can generate SVG documents that can be rendered using the aforementioned libraries. See KeenWrite's screenshots for example image renders that use Kroki. The mermaid diagrams cannot be fully rendered.

Feature request: Have mermaid generate simpler CSS/SVG by default that can be parsed and rendered by the majority of those libraries.

[jgreywolf]

@davejarvis you mention MS Word - since word does not support adding SVG into documents, I am curious how you were able to verify this...

Mermaid Chart is working with MS to publish a plug in for Word, PowerPoint and OneNote that will allow users to insert diagrams from their mermaid chart library directly. Due to limitations in the Office model SVG is not supported, so we are rendering to PNG before insert.

Actually - now that I think about it, in PowerPoint you can insert an SVG, but I think it converts to PNG during the process (and as you have mentioned above, is not rendered correctly)

[jgreywolf]

Assigning to myself to review

[ghost]

@jgreywolf

• https://support.microsoft.com/en-au/office/edit-svg-images-in-microsoft-365-69f29d39-194a-4072-8c35-dbe5e7ea528c
• https://pcauthorities.com/how-to/word/insert-a-scalable-vector-graphics-svg-in-word-2019/
• https://www.makeuseof.com/tag/insert-edit-scalable-vector-graphics-office-2016/

Due to limitations in the Office model SVG is not supported, so we are rendering to PNG before insert.

That's unfortunate. An SVG format is usually selected because it doesn't lose resolution when scaled. Using PNG images only (partially) solves the problem of embedding into MS documents and still leaves at least 13 other libraries (and countless dependent applications) unable to render MermaidJS diagrams.

Is solving the deeper problem of having MermaidJS produce SVG-compliant output not feasible?

[jgreywolf]

I was just asking in regards to the MS Word part.
I am investigating the SVG-compliant aspect

[taylorh140]

I’m curious what actions need to be taken in moving this forward. Does this imply adding something like svgdom into the mermaid library, removing the variance in browser layout engines?

[taylorh140]

I was just asking in regards to the MS Word part.
I am investigating the SVG-compliant aspect

Also I thought word recently added svg support. I’ll have to check again.

[ghost]

Also I thought word recently added svg support. I’ll have to check again.

https://office-watch.com/2016/svg-graphics-coming-to-office-at-long-last/

[ghost]

FYI, in two days I will be locked out of my account once GitHub begins enforcing MFA. Sorry I won't be able to help any further.

[willcl-ark]

I am hitting this issue using prawn-svg. Has there been any update on not using foreignObject (embedded HTML) in mermaid diagrams?

[earonesty]

years later... it still doesn't render in most things besides browsers. pie charts work. i can clean up the svg manually and get it to work. might see about making a pr, so mermaid generates "easier" svg.

[geffen]

Just ran into this trying to take SVGs into anything Adobe - Photoshop, Indesign, etc... Corrupt file from their POV.

[carlosame]

Out there, people keep posting a "list of libraries that cannot render Mermaid files" taken from this issue, which includes the EchoSVG project that I manage. And although EchoSVG's Mermaid renderings aren't perfect, it is able to render many Mermaid diagrams since 2022 (after the OP of this issue asked for it).

You need to use the CSSTranscodingHelper which supports custom properties and other modern CSS.

Some examples from the EchoSVG test suite (the SVG was taken from Mermaid's website) follow:

However it often omits the text that overflows, yet that bug has little to do with foreignObject AFAIK:

So the output is far from perfect, but better than it used to be (and preferable to the "black squares" that I hear about).

[clach04]

@ghost or any admins, please could you update the original description to link to comment #2485 (comment) for the EchoSVG mention?

[lex-gsynergy]

Wow, this is a popular issue. For me, I ran into it via react-markdown, which I am using in a proprietary web app I am working on. The code runs fine in a browser but runs into trouble during test cases, which I run on Node.

It's not the end of the world, but I'd much prefer if I can run my tiny Node-based unit tests without having to pull in a web browser. If I depend on Playwright, then IIUC it's going to download a Chrome binary and run Mermaid within Chrome. My other option is to run the whole unit test suite in Chrome.

I have two ideas that the maintainers could consider regarding what to do:

1. Can you disable the actual layout part during unit tests? IIUC, the reason for the dependency on a web browser is because that gives access to the browser's layout engine. Node has most things but not that.
2. Use a Cassowary library to lay things out. Cassowary is designed to support the same sort of constraints that a browser rendering engine will provide, and there are JavaScript libraries that will synchronous compute layouts for you.

Side benefits of Cassowary would include:

1. This may help with some of the awkward ways Mermaid must currently be invoked. Instead of needing to put things on a DOM node to get them to lay out, it should be possible to do the layout on the diagram before attaching it to the DOM at all.
2. It should be more browser independent. While all browsers are supposed to support the same standards for layout computation, it's generally not guaranteed. A JavaScript library is going to be more predictable across browsers.

[carlosame]

2. Use [a Cassowary library](https://www.npmjs.com/package/cassowary) to lay things out. Cassowary is designed to support the same sort of constraints that a browser rendering engine will provide, and there are JavaScript libraries that will synchronous compute layouts for you.

Side benefits of Cassowary would include:
[...]

Cassowary code is from 10 years ago and does not appear to be mature. Quoting slightlyoff/cassowary.js#79 (comment):

the js library is not really convenient & reliable to use

My conclusion was that Cassowary is not currently completely ready for production

[clach04]

Whilst reviewing the above (Cassowary) stumbled across https://github.com/lume/kiwi - this is not a recommendation, I've never used it. It is a research share!

[lex-gsynergy]

I think you are right, @carlosame and @clach04 , but it looks like it is just the one implementation I linked to that is abandoned, not Cassowary as a whole. I see that Apple's AutoLayout is reported to be based on Cassowary constraints.

AutoLayout might also be interesting to Mermaid. It's a wrapper of Cassowary that lets you specify constraints in UI terms (child1 must be to the left of child3) rather than raw numeric variables (child1_right <= child3_left). AutoLayout is also just interesting for showing that Cassowary is flexible enough to encode and solve UI-like constraints.

I haven't carefully tested any of these, either, but it does look like there are reasonable ways to do constraint-based layout without needing to use a browser's layout engine.

[carlosame]

it looks like it is just the one implementation I linked to that is abandoned, not Cassowary as a whole.

There are no active forks.

I see that Apple's AutoLayout is reported to be based on Cassowary constraints.

That's closed source, and needless to comment on the budget and number of employees that Apple has. "Apple can do this" isn't really an argument.

AutoLayout might also be interesting to Mermaid. It's a wrapper of Cassowary that lets you specify constraints in UI terms (child1 must be to the left of child3) rather than raw numeric variables (child1_right <= child3_left). AutoLayout is also just interesting for showing that Cassowary is flexible enough to encode and solve UI-like constraints.

That one still depends on software that was abandoned 10 years ago.

I haven't carefully tested any of these, either, but it does look like there are reasonable ways to do constraint-based layout without needing to use a browser's layout engine.

Even if something reliable and properly maintained existed, Mermaid already computes simple layouts, but complex ones are a different matter. A layout involves optimizations based on knowledge about the font families and sizes available to the user, as well as user preferences (think of the user style sheet and the user-preference media queries, both important for accessibility). This can only be done at the user agent level.

[lex-gsynergy]

Cassowary is one of the most popular constraint solving frameworks in the world, so it feels like fencing to argue about whether Mermaid can use it. I just mentioned Cassowary as an existence proof, but just focusing on that one, it's already a hugely popular framework that shows how Mermaid's constraints could be calculated without needing a browser rendering engine. This isn't a random Node library but more of a framework. To draw a comparison, this discussion is like saying regular expressions are dead just because nobody uses or maintains the original Lex program from the 70s. That sounds pretty out there, doesn't it? Nobody uses 70s Lex, but they use Flex and JFlex, the Perl compatible regex library for C, and the Java standard library. The phrase "regular expressions" means all of them, without regard to the specific implementation.

It's true that the browser render engine allows for the layout to be customized by the user's choices such as font size and potentially other things. That's one of the many benefits of the clever approach being used in Mermaid. However, the point of this issue is that there are also use cases where browser-agnostic rendering would be better.

[carlosame]

Cassowary is one of the most popular constraint solving frameworks in the world, so it feels like fencing to argue about whether Mermaid can use it. I just mentioned Cassowary as an existence proof, but just focusing on that one, it's already a hugely popular framework that shows how Mermaid's constraints could be calculated without needing a browser rendering engine. This isn't a random Node library but more of a framework. To draw a comparison, this discussion is like saying regular expressions are dead just because nobody uses or maintains the original Lex program from the 70s. That sounds pretty out there, doesn't it? Nobody uses 70s Lex, but they use Flex and JFlex, the Perl compatible regex library for C, and the Java standard library. The phrase "regular expressions" means all of them, without regard to the specific implementation.

Cassowary isn't a framework (in the sense of how the word is used in IT), it is an implementation of a variant of the dual simplex method, with several language ports. The javascript port is dead and there are no active forks. If you want your comparison to regular expressions to hold, just name a couple of active JS ports.

It's true that the browser render engine allows for the layout to be customized by the user's choices such as font size and potentially other things. That's one of the many benefits of the clever approach being used in Mermaid. However, the point of this issue is that there are also use cases where browser-agnostic rendering would be better.

It's not me who you have to convince, I'm not a Mermaid developer. If you want to open a pull request with your Cassowary-based code and volunteer to maintain it in the future, I'm fine.

But you are encouraging other people to work on it, and regarding that:

1. It would drain a large amount of developer resources, that are unlikely to be available.

and

2. To be compatible with accessibility standards, this could only be done correctly with the help of @supports rules. But with the exception of EchoSVG, none of the CSS parsers used by the tools mentioned in this thread recognize such rules, and I have done tests showing that they may not recover well from encountering them (that's the case with Apache Batik) due to not following the specification about error recovery, thus ruining the whole style sheet parsing.

[kinthaiofficial]

Non-browser Mermaid rendering is very useful for CI pipelines, documentation generation, and server-side diagram embedding. A few approaches that work:

1. mermaid-js/mermaid-cli (mmdc)
The official CLI uses Puppeteer under the hood:

npx @mermaid-js/mermaid-cli mmdc -i input.mmd -o output.svg

Works in CI with headless Chrome. The Puppeteer dependency adds ~200MB but it's reliable.

2. Playwright-based rendering (lighter alternative)

const { chromium } = require('playwright');
const browser = await chromium.launch();
// render mermaid programmatically

3. mermaid-js server (REST API)
Run @mermaid-js/mermaid-cli as a microservice that accepts POST requests with diagram text and returns SVG. Cache rendered diagrams by hash to avoid re-rendering unchanged content.

4. d2lang or Graphviz for server-side
If avoiding browser dependencies is the constraint, d2lang and Graphviz are pure native binaries that can render diagrams without headless Chrome. Not Mermaid syntax compatible, but for new projects, these are easier to deploy.

5. The WASM route (future)
Compiling Mermaid's rendering logic (which uses D3/Dagre) to WASM would enable true non-browser server-side rendering without Puppeteer. This is a non-trivial undertaking since the rendering pipeline assumes DOM APIs.

For AI-generated diagrams specifically:
LLMs can generate Mermaid syntax fairly reliably (it's well-represented in training data). A server-side rendering pipeline means you can: ask an AI to generate a diagram, render it server-side, embed in documentation, all without browser dependency.

[BettaiebMohamed]

I’ve run into the same issue when trying to use Mermaid-generated SVGs outside the browser. The reliance on foreignObject and more complex CSS seems to break compatibility with a lot of non-browser renderers (especially things like prawn-svg and Batik).

It would be really helpful if there were an option to export “plain” SVGs — something closer to what tools like Graphviz produce — even if it means sacrificing some styling or layout precision. A simpler, more broadly compatible output mode could make Mermaid much easier to integrate into document pipelines and server-side rendering workflows.

Curious if anyone has experimented with post-processing the SVG to strip unsupported elements as a workaround

[carlosame]

People are posting without reading this thread so I'd suggest to add a link to EchoSVG's wiki page about Mermaid rendering somewhere in Mermaid's website.

For example in

https://mermaid.ai/open-source/ecosystem/integrations-community.html#other

or even the FAQ (like "How to do a lightweight server-side render of Mermaid's SVG"):

https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/config/faq.md

Maybe together with an explanation about not being a good idea to restrict Mermaid to SVG 1.1 and CSS from the previous century, with all the issues about accessibility, media adaptability and implementation complexity that have been mentioned here.