-
Notifications
You must be signed in to change notification settings - Fork 8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Enable comments or annotations for mermaid diagrams in Material for MKDocs site #191
Comments
Quick additional comment: I've checked the issues/discussions in the Material for MKDocs repo, and squidfunk is very friendly and responsive if this does end up being an upstream issue. However, I haven't played around with it enough yet to justify raising an issue, and expect that the response will be "this isn't possible". |
I don't think this is something that's easily done, as there is likely a separate renderer for the mermaid markup -> HTML that doesn't necessarily get passed through/mixed in with the markdown -> HTML that |
Hold on - there seems to be a way of building in callbacks through Javascript! See this fiddle here for an example: https://jsfiddle.net/s37cjoau/3/ Here are some related issues of interest: |
Just to add one additional issue to this. It doesn't seem as though Material for MKDocs (MMK) is using the latest version of mermaid, as the ability to add font styling and word-wrapping is not working properly. For instance, this is how MMK renders the following code:
Whereas, this is how it should get rendered: Also, not sure how to fix the vertical alignment issue (i.e. blank space above the text). Only thing I have found so far is this blog post announcing the feature: https://www.mermaidchart.com/blog/posts/automatic-text-wrapping-in-flowcharts-is-here |
Looks like there has finally been some developments here: squidfunk/mkdocs-material#5758 (comment) |
There's a pull request for updating mkdocs-material and bringing the latest mermaid version into it: squidfunk/mkdocs-material#6265. This seems to address at least the styling issues that you mentioned @chrisdburr. However, the annotations is still a pending problem. |
Closed as no longer relevant. |
Material for MKDocs is the static-site generator that is used to build the Assurance Platform documentation site.
It natively supports mermaid diagrams, which is great!
However, I'm trying to see if there is a way to also make use of another feature that is also built-in to Material for MKDocs: annotations.
Annotations are simple tool-tips, which would be an excellent way to add comments to any mermaid diagrams in the documentation. For instance, adding an explanation to a graphic of an assurance case. However, there doesn't appear to be an easy way to achieve this.
For instance, the following doesn't work, because it (unsurprisingly) throws a mermaid syntax error:
Neither does it appear to work to attach an
annotate
class to one of the nodes in the diagram, and then follow the instructions listed here, because although the class assignment works, there is no way to add the actual annotation text without encountering the same issue as above:@AoifeHughes or @kallewesterling: curious to know if you can think of a workaround, or whether it's just not possible due to the way that the various markdown parsers and plugins interact.
If not, then it would be good to know if there's some other way to achieve something similar to annotations, or just have a way to add comments to mermaid diagrams in the documentation.
This page is the one I'm playing around with at the moment, as it would be helpful to have comments alongside the introduction of the core elements:
https://github.com/alan-turing-institute/AssurancePlatform/blob/documentation/site/docs/guidance/core-elements.md
The text was updated successfully, but these errors were encountered: