CODEWITHSUNDEEP
mkdocsmermaid
mejoz
mejoz

Reputation: 135

Exclude mermaid code blocks for highlighting with Codehilite (MkDocs)

I'm trying to generate a documentation from markdown files via mkdocs (with material) to publish on gitlab. My files include code blocks and mermaid diagramms, which are declarated the same (differentiated in the language). I would like to use CodeHilite to beautify the code blocks but the mermaid blocks will also be processed by it as code blocks and than will get ignored by the mermaid-mkdocs plugin. Is there a way, I could exclude certain blocks from codeHilite or any other change to use both together?

Upvotes: 0

Views: 1033

Answers (2)

fralau
fralau

Reputation: 3839

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.

Upvotes: 2

streuspeicher
streuspeicher

Reputation: 158

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

Upvotes: 2

Related Questions