Redmine

Mermaid has become widely adopted for creating diagrams in Markdown-based tools, and is supported by major platforms such as GitHub, GitLab, Azure DevOps, and Obsidian. I think Mermaid support would be a valuable addition to Redmine.

As a side benefit, having Mermaid.js available in Redmine could also support future UI improvements beyond Mermaid markup in formatted text. For example, it could be used for workflow visualization (#559) or issue dependency graphs (#2448).

Thanks for the patch. Overall, I like the implementation. The amount of core changes is relatively small, Mermaid is loaded only when needed, and features such as lazy loading and one-time initialization are implemented cleanly.

I also agree with Go MAEDA that having Mermaid support available directly in Redmine could enable additional use cases beyond wiki content.

One concern is that Mermaid is a rather actively developed project with frequent releases. Bundling it in Redmine core means tracking Mermaid updates, security fixes and related third-party dependencies over time. An alternative approach could be an optional Mermaid CLI/CGI integration with server-side SVG/PNG generation, allowing each Redmine installation to decide whether to enable it and keeping Mermaid outside the core dependency chain.

However, this would also make the integration and deployment more complex. Therefore, I still support the proposed JavaScript integration, as it is simple, widely adopted and probably the most practical solution for most Redmine installations.

Regarding the current patch itself, I only have one question:

mermaid.run({ nodes: [container], suppressErrors: true })

From my testing, with suppressErrors: false Mermaid parser and validation errors are propagated to the Promise rejection handler, for example invalid diagram types or syntax errors. This causes the .catch() block to run, while the original code block remains visible.

With suppressErrors: true, these errors no longer seem to reach the .catch() block, so no error is logged and the Mermaid-generated error rendering is shown instead.

Would it make sense to use suppressErrors: false here, hide the Mermaid error output, and log or display the actual parser error object?
The error details often include the exact line and syntax problem, which can be very helpful for users debugging Mermaid diagrams.

Florian Walchshofer wrote in #note-3:

One concern is that Mermaid is a rather actively developed project with frequent releases. Bundling it in Redmine core means tracking Mermaid updates, security fixes and related third-party dependencies over time. An alternative approach could be an optional Mermaid CLI/CGI integration with server-side SVG/PNG generation, allowing each Redmine installation to decide whether to enable it and keeping Mermaid outside the core dependency chain.

Thank you for the feedback.

I have not tested this approach yet, but I think it should be possible to enable Mermaid conversion only when Mermaid CLI is available, similar to other features that depend on external commands such as Ghostscript or ImageMagick.
Personally, I prefer the Mermaid.js approach because the implementation is simpler. However, if the Mermaid CLI approach is considered preferable given the maintenance burden of keeping Mermaid.js and its dependencies up to date, I would respect that decision.

With suppressErrors: true, these errors no longer seem to reach the .catch() block, so no error is logged and the Mermaid-generated error rendering is shown instead.

You're right. I've updated the pull request. https://github.com/ishikawa999/redmine/pull/19/changes/71ca601f747d8cccb67816ddb9ec87f1ebebb5fb

Florian Walchshofer wrote in #note-3:

[..]
One concern is that Mermaid is a rather actively developed project with frequent releases. Bundling it in Redmine core means tracking Mermaid updates, security fixes and related third-party dependencies over time. An alternative approach could be an optional Mermaid CLI/CGI integration with server-side SVG/PNG generation, allowing each Redmine installation to decide whether to enable it and keeping Mermaid outside the core dependency chain.

That also means the integration can break after a server-side Mermaid CLI/CGI update. Additionally, server-side rendering requires Puppeteer, which makes installation and maintenance much more complex.

Overall, I am in favor of bundling the JS library inside Redmine. We can cut new releases for important upstream security fixes, just as we already do for other dependencies.

It will be greate that PDF export also render mermaid blocks correctly!
Thanks

Helder Costa wrote in #note-8:

It will be greate that PDF export also render mermaid blocks correctly!

Thanks for the suggestion. I agree that rendering Mermaid diagrams in PDF exports would be a great addition. However, supporting PDF export would significantly increase the scope of this feature.

In my opinion, we should first focus on making Mermaid available on Redmine's web pages, and consider PDF export as a future improvement after the web support is complete.

I updated the implementation to support Mermaid.js 12.0.0 and incorporated 0003-parse-error-to-flash-error-message.patch by Florian Walchshofer, along with some other changes, and pushed the updates to https://github.com/ishikawa999/redmine/pull/19 .

I have tested the latest patch, and I have not found any issues that would block merging it.

Since there is still enough time before Redmine 7.1.0, I am planning to commit this to trunk in the next few days. This will allow more people to try Mermaid support in real-world use and give us time to address any issues that may be found before the release.

Please let me know if you have any concerns.

Go MAEDA wrote in #note-11:

I have tested the latest patch, and I have not found any issues that would block merging it.

Since there is still enough time before Redmine 7.1.0, I am planning to commit this to trunk in the next few days. This will allow more people to try Mermaid support in real-world use and give us time to address any issues that may be found before the release.

Please let me know if you have any concerns.

I'm in favour of adding this to the core as soon as possible.

Go MAEDA wrote in #note-13:

I have updated the patch so that Redmine no longer bundles mermaid.js. The two attached patches replace the previous ones.

Thank you for pointing this out and for the updated patch.
As you mentioned, now that mermaid 12 embeds elkjs, which is licensed under the EPL-2.0, into mermaid.min.js, it cannot be distributed with Redmine, which is licensed under the GPLv2. mermaid.min.js bundled more libraries than I had expected, and I failed to notice this when updating it.

I think having administrators install mermaid.js instead of bundling it is the best approach to deliver this useful feature to users without violating the licenses.