add support for rendering diagrams with mermaid #184
Conversation
[mermaid][mermaid] generates diagrams and flowcharts from text in a similar manner as markdown. This adds support for rendering diagrams from any markdown code blocks with the language tag `mermaid`. For example the code block: ```mermaid sequenceDiagram Alice->>+John: Hello John, how are you? John-->>-Alice: Great! ``` Will now render an inline SVG diagram of the sequence instead of the raw `<code>` block. Keeping diagrams as code in this way makes it significantly easier to keep diagrams up to date with the documentation, and can make reviewing changes to them easier. The implementation takes advantage of the existing dependecy on node.js to install and execute the mermaid cli tool that translates the various diagram code into SVG. A timeout is added to execution to workaround an issue where the cli tool [fails to terminate on error][fail-exit]. [mermaid]: https://mermaid-js.github.io/mermaid/#/ [fail-exit]: mermaidjs/mermaid.cli#77
There was a problem hiding this comment.
Smashing (my approval doesn't mean much though as I'm not a maintainer of this repo)
We (PaaS) use mermaid diagrams a bit using https://hackmd.cloudapps.digital/ having these in the tech docs would be great
|
Human-readable version-controlled diagrams in the docs - such an excellent addition ✨ I realise this is a work in progress and this is probably on the to-do list or out of scope, but it would be good if the diagrams could be made to look like GOV.UK. Also for accessibility, it would be good to document how to add alt text to these diagrams. Great work - this is a super useful feature 🙌 |
the deafult mermaid themes for diagrams don't quite fit the GOV.UK "brand" colors, and creating the CSS to get the colors pretty is out of scope, so this just sets it to use the "neutral" (grayscale) theme, which at least doesn't clash with anything.
|
@bravegrape RE: looks... I agree, the default theme/colors does clash a bit with the GOV.UK "brand" ... I don't fancy spending hours tweaking CSS to paint this particular shed ... however there is a grey-scale theme, which will likely be less controversial, I'll switch it to use that. |
|
@chrisfarms We might be able to ask the Design System team to help us with colours (and make sure things like the colour contrast meet WCAG 2.1 requirements). @bravegrape great point and sorry I should have added a note here that @chrisfarms and I had a quick chat about accessibility the other day. I'm planning to catch up with our accessibility team here to check where we'd stand on using Mermaid accessibility-wise. |
|
@m-green and @chrisfarms I'm sure you're on top of things on the accessibility front 😄 Being on a mid-week-once-in-5-years national day off, I couldn't keep away from exciting new features being developed for the GOV.UK tech docs template. I do now realise my alt text docs suggestion might have been a bit narrow... It would be great to find out more about accessibility for diagrams-as-code and if their "code" nature can help with accessibility 🤔 |
m-green
moved this from Triage
to Backlog
in Technical Documentation Template project board
What
This adds support for rendering diagrams from any markdown code blocks with the language tag
mermaid.For example the code block:
Will now render an inline
<svg>diagram of the sequence instead of the raw<code>block.Before
After
Why
Keeping diagrams as code in this way makes it significantly easier to keep diagrams up to date with the documentation, and can make reviewing changes to them easier.
We often use sequence or state diagrams in internal team manuals to give visual aids to complex systems or architectures.
An example can be seen in the Alertmanager documentation within the Reliability Engineering Team Manual ... if a minor change is required to this diagram, the author would need to have the original source or start again from scratch. But with the ability to use diagrams directly from markdown, the source of the diagram would be easily update-able and preview-able from the middleman server.
How
mermaid generates diagrams and flowcharts from text in a similar manner as markdown.
The implementation takes advantage of the existing project dependency on node.js to install and execute the mermaid cli tool that translates the various diagram code into SVG. A timeout is added to execution to workaround an issue where the cli tool fails to terminate on error.