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.

[kamilkrzyskow]

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.

The link from #2170 (comment) is broken BTW:

• https://github.com/facelessuser/pymdown-extensions/blob/master/docs/src/markdown/_snippets/uml.txt#L5

However, this might be a case of the X Y Problem

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.

There is an open Issue for mermaid styling:

• Mermaid: improve link discoverability #5619

@squidfunk
What I would like to propose is to add an option to be able to add custom styles to the mermaid shadow root, like I did in the hook above.

extra:
  extra_shadow_root_css:
    - assets/stylesheets/mermaid.css # I don't know if relative paths are supported in the shadow root
    - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css

From my testing I don't see the link to be fetched many times, the browser is smart enough to fetch it only once despite including it in every mermaid block.

[squidfunk]

Thanks for suggesting. We have to be very careful for the maintenance nightmare that is adding more and more things under extra, and honestly, this looks very, very weird. We would need to somehow pull all of this through from mkdocs.yml to the application where we render Mermaid.js. What if we add another integration for another library that also mandates shadow root? Another setting in extra? My point is that this feels like a huge bandaid that I'm not comfortable maintaining.

If there are no side effects, we can open the shadow root. However, I need to trust you on that one, because of my currently limited time due to the heavy focus on the big topics to push this project further.

[kamilkrzyskow]

Great, I shall wait a bit for facelessuser to reply, and later will do a bit more testing with the open mode override in docs that use them, like then one mentioned in the issue above 👍

EDIT:
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.

[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