New developments on mermaid (native support) and plugin.

[fralau]

Thanks @squidfunk for this interesting development (#2170) 👍 ! I am following it with great interest, as maintainer of mermaid2 plugin)

mermaid is a great tool, which works well with mkdocs; but it internals can be a bit messy, and sometimes finicky, for demanding applications. Sometimes, it becomes a rabbit hole.

Since material is a de facto standard for mkdocs (why using another theme 🙂 ?), we should welcome anything that can make the use of mermaid, easier and safer. And if those developments can avoid using a plugin for a whole category of users, so much the better (principle of economy).

If you are asking right now "why should I bother to use the mermaid2 plugin?", then you might be in the category that actually doesn't need it. That plugin is written for two different demographics:

1. People who have just enough notions and markdown to run mkdocs, but don't want to have anything to do with css, javascript, html, etc.. They just want mardkown, mermaid2 code, and plug'n play (just mention mermaid2 in their list of plugins).
2. At the other end, people who want a solid framework to use javascript with mermaid (callbacks), etc.

In general I try to keep the mermaid2 plugin aligned with the material theme (which has a special status), but also
compatible with other themes.

The bottom line is that I am interested (if I manage) in keeping the mermaid2 plugin aligned to the future improvements of the material theme for mermaid, so that it can exploit them. 👍 While keeping the options open for those who don't use material.

[squidfunk]

Thanks for your ideas and work on this plugin.

mermaid is a great tool, which works well with mkdocs; but it internals can be a bit messy, and sometimes finicky, for demanding applications. Sometimes, it becomes a rabbit hole.

I agree completely. The direction I'm aiming for with the native integration is to make usage of Mermaid for the user as frictionless as possible. Currently, the only thing that needs to be done is to configure Superfences to read mermaid blocks, the rest is done by the theme itself. Moving this to a plugin wouldn't make much sense, because what I can provide with a native implementation is perfect integration with Material for MkDocs other signature features like instant loading and color palettes (i.e. dark mode). If you would add this to your plugin, this would be specifically tailored to Material for MkDocs, as I don't know any other theme that supports those features, and if they did, implementation would likely be different.

In general I try to keep the mermaid2 plugin aligned with the material theme (which has a special status), but also
compatible with other themes.

I've linked to your plugin in the footnote for users who don't want to use the native integration. It's optional after all. The Mermaid integration isn't done yet and is deliberately situated in a later funding goal, so we can flesh out the bugs before releasing this to the public 😊 Thus, your plugin makes perfect sense, and even after the release, other themes or users building their own would likely want to integrate with Mermaid.js. We don't try to replace your plugin, it's just that we can achieve a deeper integration if we go the native way.

[fralau]

If you would add this to your plugin, this would be specifically tailored to Material for MkDocs, as I don't know any other theme that supports those features, and if they did, implementation would likely be different.

Yes, in case of need I might have to test for the presence of the material theme (and its version, I guess). Or else, some obvious sign of its presence, such as a specific class or id in the HTML code (I already used this tactics).

We don't try to replace your plugin, it's just that we can achieve a deeper integration if we go the native way.

Yes I can see how this project makes good sense. MkDoc's ecosystem is still evolving, and the notion of "optimum solution" is not fixed yet. It is inevitable that we have more than one way to do things, because none covers all use cases.

I'm all in favor of standardization so I won't mind if a better or more general solution is found than the mermaid2 plugin. And if the plugin is still the proper way to go, so be it... 🙂