search

alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

add support for rendering diagrams with mermaid #184

Open chrisfarms opened 4 years ago

chrisfarms commented 4 years ago

What

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.

Before

before

After

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.

bravegrape commented 4 years ago

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 🙌

chrisfarms commented 4 years ago

@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.

m-green commented 4 years ago

@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.

bravegrape commented 4 years ago

@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 🤔