Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
We use Mermaid extensively in statically-generated documentation sites, mostly for workflow and sequence diagrams. We've started building a Drupal-based application, where we'd like to use Mermaid for similar reasons.
Proposed resolution
Add input filter to render Mermaid graphs.
Remaining tasks
I already have a basic working implementation. So next steps would be to commit that to a feature branch for further testing and iteration.
| Comment | File | Size | Author |
|---|
Issue fork mermaid-3468773
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
compare
Comments
Comment #2
joachim commentedNice idea, but I think this belongs in the GraphAPI module.
Comment #3
ergonlogicHi @joaquim. Thanks for taking a look at this.
Could you clarify why you think this feature fits better in GraphAPI than in Mermaid Integration? The Mermaid JS library is already provided in the other module.
Comment #4
joachim commentedThe Mermaid module is an extension to GraphAPI which provides a specific graph renderer.
The way to interact with a graph is via the GraphAPI module.
Comment #5
ergonlogicI see that we already have a TGF filter plugin in GraphAPI. But since the Mermaid filter plugin will depend on the external library, we'd need to add the library that in GraphAPI too, instead of just re-using the one provided by the Mermaid Integration module.
I'd also like to support various themes, and maybe later other Mermaid config. Code to handle this could probably be extracted into a MermaidTrait, to further reduce duplicated code between both Filter and Graph plugins.
Comment #6
joachim commented> But since the Mermaid filter plugin will depend on the external library, we'd need to add the library that in GraphAPI too, instead of just re-using the one provided by the Mermaid Integration modu
I don't really follow this, sorry. The Mermaid module is meant to be used as an extension to GraphAPI. You don't need to add the Mermaid library to GraphAPI, you just enable both modules and then your graphs can be rendered with Mermaid.
Comment #7
ergonlogicI agree that's mostly what's currently implemented there, along with adding the Mermaid JS library. But it's called "Mermaid Integration", uses the
mermaidnamespace, and resides atdrupal.org/project/mermaid, notdrupal.org/project/graphapi_mermaid.I'm suggesting adding an input filter that renders Mermaid syntax (using only the Mermaid library). It doesn't really need GraphAPI functionality at all. It's basically just replacing
[mermaid]...[/mermaid]blocks with<pre class="mermaid">...</pre>.For reference, I've attached a patch (for the
mermaidproject). Note that it uses the Mermaid JS library provided by the Mermaid Integration module, but otherwise stands alone, using only Drupal core.It also allows for the selection of a Mermaid theme, which partially duplicates
MermaidEntityRelationship::defaultOptionsForm. As I'd mentioned previously, this seems like an opportunity to consolidate Mermaid configuration functionality in aMermaidTrait. I'd argue that such a trait ought to also live in the Mermaid module, and would certainly seem out-of-place in GraphAPI.For the sake of having the patch work, I've moved this issue back to Mermaid Integration. If you insist, I'll move it back to GraphAPI, and revise the patch accordingly.
Comment #8
ergonlogicSince there's a patch now, I suppose this should be "Needs review"
Comment #9
joachim commentedI've only just remembered how Mermaid graphs work by parsing text... So I was completely misunderstanding this, sorry!
So yes, I can see this input filter is Mermaid-specific.
But then I'm not 100% sure it belongs in this module, as this module is the GraphApi integration. Someone wanting just your input filter ends up having to install GraphApi which they don't want. Not sure how best to resolve this though.
Comment #10
joachim commentedOk, I've had an idea:
- we keep the mermaid libraries in the mermaid module
- we move the GraphAPI support to a submodule called mermaid_graphapi
- we add the new input filter to another submodule called mermaid_filter
Comment #11
ergonlogicThanks, @joachim. That all makes sense.
Comment #12
ergonlogicI created #3470073: Move GraphAPI support to a submodule to handle the first part.
Comment #13
ergonlogicLet's get #3470073: Move GraphAPI support to a submodule done first, so that the text filter stuff can more cleanly be added as a sub-module.
Comment #14
ergonlogicI've pushed a commit that's mostly the same as in the patch, except in a sub-module, per #3470073: Move GraphAPI support to a submodule, with the change in namespace, etc. Obviously, this branch extends the one from that issue.
Comment #15
ergonlogicI merged this branch to 1.0.x.
The fix here is a sub-module that shouldn't affect any of the rest of the codebase.