Exclude mermaid code blocks for highlighting with Codehilite (MkDocs)

Solution 1:

If you use the mermaid2 plugin, the readme contains a section on Using Mermaid and code highlighting at the same time.

You would have to use superfences in this way:

markdown_extensions:
  - pymdownx.superfences:
      # make exceptions to highlighting of code:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

Note: @streuspeicher is correct in saying you don't have to use the mermaid2 plugin to exploit mermaid diagrams, if you have an average knowledge of mkdocs, javascript libraries, etc.

I designed mermaid2 [disclosure] with two types of users in mind:

1. Beginners who have little knowledge of css, javascript etc and basic needs with mermaid. They simply have to declare mermaid2 under their list of plugins, and it's going to work out of the box.

2. On the other extreme, advanced users who really want to tweak their use of mermaid, with theming, callbacks, etc. and want to have a reliable framework to do that.

If you are in the sweet spot (of having basic needs with mermaid diagrams, and you are confident with extensions, css, javascript, etc.) you can happily do without mermaid2.

Solution 2:

I had exactly the same issue and found the following solution by using the pymdownx extension (bundled with mkdocs material theme, see https://squidfunk.github.io/mkdocs-material/extensions/pymdown/):

Include the following into your mkdocs.yml:

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

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

I do not use any additional mkdocs plugins for mermaid like mermaid2.

This solution is based on https://github.com/squidfunk/mkdocs-material/issues/693#issuecomment-411885426