Mkdocs-material: Support for mermaid diagrams

[ng28]

Looking for an enhancement. Is there any plan to support the diagrams usage in material?

[squidfunk]

What are mermaid diagrams?

[facelessuser]

This question was brought up in pymdown-extensions: https://github.com/facelessuser/pymdown-extensions/issues/60. SuperFences is used to create the UML diagrams currently accessible, but you can configure SuperFences to generate such blocks differently, then include necessary JavaScript and CSS to render them in the browser.

I don't provide multiple different examples of every UML library out there, and I leave it up to users to do the work for their favorite library. You are free to create a wiki page over at pymdown-extensions to detail how you got it working so that others can get going with mermaid (I think I allow the public to edit/create pages).

Anyways, check out the linked issue for more info.

[ng28]

Since the mermaid support need to be added as part of the extension, it can be closed.

[facelessuser]

It doesn't need to be added as part of the extension, you just need to utilize the extension options to add support in your documents yourself.

[romanr]

Anyone been able to do it?

This discussion mentions "you should be able to do it" but no pointers where to look.
https://www.mkdocs.org/user-guide/configuration/ references nonexistent site: https://pythonhosted.org/Markdown/extensions/index.html

I googled the "python markdown", found https://python-markdown.github.io/extensions/
But there's no mention of mermaid even in "3rd party extensions"

On mermaid website https://github.com/knsv/mermaid there's no mention how to integrate it either.

[gilbsgilbs]

@romanr
The trick is:

• to include MermaidJS assets in your bundle
• to use Pymdown's Superfences extension to make mkdocs build "mermaid" code sections into div with the "mermaid" class.

This is the relevant section in the doc: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_div_format

extra_css:
  - https://unpkg.com/[email protected]/dist/mermaid.css
extra_javascript:
  - https://unpkg.com/[email protected]/dist/mermaid.min.js

And then write your mermaid code as follow:
````markdown

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

````

[dobl1]

Not working anymore ?

[facelessuser]

@dobl1, you would need to be very specific in what you are doing that isn't working. Also Material doesn't support Mermaid out of the box. This requires users to setup their own custom fences via pymdownx-superfences. In addition, if Mermaid changes how they do things, then you may need to provide your own custom formatter.

Regardless, I'm not sure this is a Material question. Maybe hop on over to pymdown-extensions and provide actual details that can be used to help guide you to a solution?

[rwoldu]

for me, links don't work anylonger,
maybe because of the new security implementation with mermaid-version 8.2: https://mermaid-js.github.io/mermaid/#/?id=special-note-regarding-version-82 ?
If yes, my question would be where to set securityLevel: 'loose' or =false.

I'm using pymdown-extensions version 5.0

my mkdocs.yml (currently):

extra_javascript:
 - https://unpkg.com/[email protected]/dist/mermaid.min.js

markdown_extensions:
- pymdownx.superfences:
    custom_fences:
      - name: mermaid
        class: mermaid
        format: !!python/name:pymdownx.superfences.fence_div_format

my mermaid-code example:

A --- B
click B "https://www.google.com"

[facelessuser]

I'm assuming you'd include it in your own JavaScript file which you would also need to include.

[jstockdi-marstone]

I was able to get this working. Updating the ticket with the latest mermaidjs version number:

```markdown_extensions:

• pymdownx.superfences:
  custom_fences:
  - name: mermaid
  class: mermaid
  format: !!python/name:pymdownx.superfences.fence_div_format

extra_css:

• https://unpkg.com/[email protected]/dist/mermaid.css
  extra_javascript:
• https://unpkg.com/[email protected]/dist/mermaid.min.js

````
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

````

[DanielChuDC]

https://unpkg.com/[email protected]/dist/mermaid.css is not found

Got this error message

Cannot find "/dist/mermaid.css" in [email protected]

Is this normal?

[facelessuser]

Yes because Mermaid no longer provides CSS assets. They have an internal system that you configure through options to use different themes (or you can turn off themes and provide your own
CSS as pymdown-extensions does in it's documentation: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences.

This is more a Mermaid question though.

[DanielChuDC]

Thank you @facelessuser !

[fralau]

Just in case, there is now a mermaid plugin (which I'm maintaining) called mkdocs-mermaid2 which is compatible with superfences:

https://github.com/fralau/mkdocs-mermaid2-plugin

[squidfunk]

Why can't we just use custom fences, which is natively supported by SuperFences? What does the plugin do "more"?

[fralau]

For complete beginners who don't know anything about the beauty of SuperFences, this plugin would be a solution out of the box.

For advanced users who really want to tweak the diagrams, the plugin provides documented use cases and allows good flexibility, typically if you want to use the mkdocs.yaml file to pass arguments to the javascript initialize() function. It also documents how to declare your own callback javascript function.

For Superfences users who are in the goldilocks zone, I wouldn't suggest a change (if it ain't broke, don't fix it 🙂). The plugin's doc shows how to make it work with SuperFences, so IMHO it should be a complement, not an alternative.

[squidfunk]

Thanks for the explanation! I still have the reference documentation for using Mermaid diagrams with Material for MkDocs on my list and will think about what to recommend. Personally, I have had a great experience with SuperFences, but I'll try your plugin and see whether it provides a significant improvement of the user experience.

[facelessuser]

I have no comments on whether the plugin is good or not, only that I know @fralau was working on it. I'd be interested to hear if people find it helps. I know it still relies on SuperFences. But I haven't bothered to look into anything else. I think once I got Mermaid up and running (and recently styled) the way I wanted, I had no need to revisit.

If I get some time, maybe I'll try it out. If it smooths over some pain points, I wouldn't mind referencing it from SuperFences documentation when I talk about Mermaid. I'd love to offload Mermaid questions 🙃 .

I joke, but I only get Mermaid questions on rare occasions. But even still, I'd much rather focus on answering questions more pertinent to the extensions themselves opposed to custom use cases 🙂.

[s1monj]

I am a complete beginner and could not set config params using custom fences, even after carefully stepping through the Advanced Mermaid Notes and trying both snippets as well as extra_javascript imports.

However setting the config in the plugin worked nicely, eg

plugins:
  - search
  - mermaid2:
      arguments:
        sequence:
            mirrorActors: false

I since discovered that config can also be applied via Directives, which works with the custom fences (without the plugin)

'''mermaid
sequenceDiagram
  %%{init:{'sequence':{'mirrorActors': false}}}%%
  participant John
  participant Alice
  Alice->>John: Hello John, how are you?
  John-->>Alice: Great!
'''

[fralau]

@s1monj that is useful feedback that seems to confirm how things are evolving. No plugins for Mermaid are needed, if the user is in the "Goldilocks zone" , i.e. :

1. Has working knowledge of MkDocs configuration (mkdocs.yaml, markdown extensions and extra javascript)
2. Needs only "out-of-the-box" Mermaid diagrams

When diagrams get more complicated (initiazation sequences, callbacks, etc.), then things get different. At some point, the requirements will exceed the personal ressources (Competence/Time/Interest) one is willing to invest.

Indeed, mermaid Directives are a great innovation to solve "one-off" needs (i.e. there are a couple of mermaid diagrams in the project and one needs to define how _that specific_ diagram should behave).

The mermaid2 plugin is more aimed at those who require a _framework_ to work with Mermaid diagrams. That could be:

• Users who don't want to bother with the markdown extensions or javascript.
• Projects that need to deal with a number of Mermaid diagrams, and want to standardize how diagrams should behave or look like.
• Complicated cases that need callbacks, javascript injections, etc.

Note that the Directives and the mermaid2 plugin should be able to work together, to a large degree.