docs: Render mermaid graphs #568
Conversation
Adds the [mermaid2 plugin] (https://github.com/fralau/mkdocs-mermaid2-plugin) which enables mkdocs to render mermaid diagrams.
|
Adding a plugins:
- mermaid2
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom |
mkdocs.yml
Outdated
| - pymdownx.superfences: | ||
| custom_fences: | ||
| - name: mermaid | ||
| class: mermaid | ||
| format: !!python/name:mermaid2.fence_mermaid_custom |
There was a problem hiding this comment.
Hey @lewismiddleton! Thanks for your contribution and for spotting this issue, very much appreciated!
In my other mkdocs project I did the following:
| - pymdownx.superfences: | |
| custom_fences: | |
| - name: mermaid | |
| class: mermaid | |
| format: !!python/name:mermaid2.fence_mermaid_custom | |
| - pymdownx.superfences: | |
| custom_fences: | |
| - name: mermaid | |
| class: mermaid | |
| format: !!python/name:pymdownx.superfences.fence_code_format |
For me it seems like a healthier change as it doesn't require the extra dependency to be installed, would you mind giving it a shot see if it renders as you would like compared with mermaid2.
Thanks in advance!
There was a problem hiding this comment.
Yeah I agree, a better solution if it works. I wasn't able to get that working, give it a try on your environment and see what you think?
You're right though in that the docs say it should be sufficient. I'm curious to know what the difference is between this project and others (if there is actually an issue - idk maybe my environment is just differnet)
There was a problem hiding this comment.
I did try it and it worked.
Worth mentioning though that I was running my doc website through a mkdocs serve and reaching it on localhost:8000 through my browser and not via the mkdocs build, it seems like you were using the build method and I don't know if that may cause some differences in the rendering.
Regardless I have another website with those options hosted on GitHub pages that is working fine as well for rendering the mermaid graphs.
Let's give it a go with only the suggestion above, merge the PR, then if it's doesn't work we'll review the addition of the plugin.
There was a problem hiding this comment.
Yeah I was using poetry run mkdocs build --strict but can confirm mkdocs serve works on my machine too.
I've reverted the commits and pushed the suggested change.
There was a problem hiding this comment.
Awesome! Thank you for your patience and making the suggested changes ❤️
And good to know it doesn't behave the same with a mkdocs build!
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #568 +/- ##
=======================================
Coverage 85.79% 85.79%
=======================================
Files 31 31
Lines 1218 1218
=======================================
Hits 1045 1045
Misses 173 173
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Add the plugin as a dependency as per installation guide.
poetry add mkdocs-mermaid2-plugin --group docsAdd to the
mkdocs.ymlvia plugins syntaxThis on it's own is sufficient to get the diagrams to render.
Resolves: #567