Search code examples
mkdocsmermaid

How can I use codehilite and mermaid together?

We generate documentation using mkdocs with the material theme and until now have used the codehilite extension. I've now added mermaid using a method described here: https://github.com/squidfunk/mkdocs-material/issues/693

First, my markdown:

# Examples

## Mermaid
```mermaid
graph LR
    a[Start] -- b[(Storage)]-->d[End]
```
## Code

```
#!/usr/bin/python
import tensorflow as tf
```

My mkdocs.yml:

# Project information
site_name: Test
site_description: 'Mermaid with CodeHiLite'

theme:
   name: material
   feature:
      tabs: false

extra_javascript:
   - 'custom_content/mermaid.min.js'

markdown_extensions:
   - codehilite

In this configuration the mermaid code is not rendered as a diagramm but the code is syntax highlighted.

Codehilite

If I extend my mkdocs.yml to add mermaid like this:

# Project information
site_name: Test
site_description: 'Mermaid with CodeHiLite'
theme:
   name: material
   feature:
      tabs: false

extra_javascript:
   - 'custom_content/mermaid.min.js'

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

then the mermaid diagrams are rendered properly but the code is not syntax highlighted.

Mermaid

If I change the markdown to add the language to the code block

``` python
#!/usr/bin/python
import tensorflow as tf
```

then both code and diagram are rendered correctly. The problem I have is that the existing documentation doesn't specify a language and until now that worked.

Any ideas how to get these two extensions to work together better? Or am I just going to have to tell the developers to update their markdown?

Solution

  • For a prepackaged solution to integrate mermaid diagrams into mkdocs, there is now the mkdocs-mermaid2 plugin, which I'm maintaining.

    For code highlighting, it also contains an example of how to make it work with the superfences plugin.

    It may be especially useful if one needs to pass arguments to the initialize() method of the mermaid renderer, to tweak the look of diagrams.