Mermaid with Icons

[HelgeKrueger]

Consider the simple mermaid diagram:

flowchart LR
    A[fa:fa-user Alice] --> B[fa:fa-user Bob]

See also https://mermaid.live/edit#pako:eNpNj7EOwjAMRH8l8tz-QAYkKthggQ3SwSRuGymJqzQRQlX_nVCkgifr-e50nkGzIZDQOX7qAWMSp4sKosz-3qHssM4TRbF3VlMr6nonmn_e8KOFCjxFj9aUnPljVpAG8qRAltXZfkgKVFiKEHPi6ytokClmqiCPBhMdLPYRPZRYN230aGziuMERw435J6L1fP7WX79Y3k0NRRw

I want the icons to properly be included in mkdocs-material.

I followed Additional CSS to add the fontawesome.css that should contain the style definition, but the icons don't show up.

The relevant mkdocs.yml should be

extra_css:
  - stylesheets/fontawesome.css
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

[kamilkrzyskow]

Hello @HelgeKrueger,
please provide a minimal example reproduction, with all used files. Without it I can only guess blindly. The site you've provided does define the Font Awesome font family and then the font family is set to be used in that Mermaid diagram, and later the CSS for the diagram defines something like:

.fa-user::before {
  content: "\f007";
}

which is the code for the "letter" representing that human icon. I don't know what is not working on your end. Perhaps you only need to enforce the usage of the font family in the diagram or perhaps something else is amiss.

https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#customization

[HelgeKrueger]

Attached is a minimal failing example:

example.zip

From looking at it from inspector, it seems as if the CSS is not being applied properly. The stylesheet is being loaded though.

[squidfunk]

I meant extra_shadow_root_css as a general extra key for all libraries that would be inside a shadow root. The css can style according to IDs and other unique values for each injected shadow root.

I know, but sorry, no, we can't introduce more an more degrees of freedom. Overseeing the impact of changes in the light of users being able to customize everything is already a gargantuan task, I'm not interested in making my work even harder 😅

[matthiasPOE]

So what is currently the correct way to get the icons working on mermaid charts? Having the icons available especially on a huge chart is a must to distinguish between certain elements

[mark4409]

Yes, I would also like to know this

[squidfunk]

Please use the search. This question has been asked several times, and IIRC, some workarounds have been proposed.

[facelessuser]

I just saw this and realize I was mentioned but never responded:

So in #2170 (comment) @facelessuser is mentioned as the one who suggested the usage of a shadow root. On his docs, I see that he's using open shadow roots with the Material theme. So I would like to ask him for a second opinion about the "because it might lead to other side effects we are currently not aware of, so very thorough testing would need to be done" claim.

In the early days of when I added Mermaid support, there were real issues with how SVG elements were managed with Mermaid in general. It was far more reliable to generate Mermaid images on the backend and include them (like they did in their own documentation, though this has changed in recent versions). Some issues where objects disappearing in unrelated diagrams when one was hidden in a Tab. These weren't problems I was guessing at, they were well understood. The shadow root approach fixed many of these issues by isolating things within the shadow root. There was no shared, faulty objects across diagrams. This was the main reason for implementing the shadow root.

I don't really want to change the shadow root mode, but it was a means to an end of being able to style the insides of the mermaid shadow root with an external JavaScript script, but perhaps this suggestion is unnecessary.

Styling was not really a motivation to use shadow root.

In recent versions of Mermaid, I have found more and more diagrams are viable as many are better formed and more consistent. The main diagram I wouldn't use from the basics is probably the gannt chart which still can exhibit some weird scaling issues at times. This may or may not be due to some combinations of options I use, but it is what it is. My findings are only suggestions.

I stand by the decision to use the shadowroot back when I implemented. The issues I was facing were very well understood, and it was absolutely necessary to work around the inconsistent and poorly managed rendering of earlier Mermaid versions. Particularly bad behaviors with diagrams that were hidden and unhidden when nested in tabs. But it is likely that it could be abandoned moving forward. I have not yet tested some of the problematic cases that caused me to start using shadowroots without shadowroots.

For my uses, I might not abandon the shadowroot as things work great for me as is, and I haven't yet run into a situation where I personally need something that is not compatible with my approach, but that certainly could change if I run into such a scenario. What I do though doesn't have to be what guides Material for MkDocs. I will simply state that the shadowroot, in the most recent versions of Mermaid, may not be necessary, but it was in earlier versions.