Skip to content
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.

Sign up for GitHub

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

Jump to bottom

add support for rendering diagrams with mermaid #184

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

add support for rendering diagrams with mermaid #184

wants to merge 3 commits into from

Commits on Nov 14, 2024

  1. Add support for rendering diagrams with mermaid 

    [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].

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.

[mermaid]: https://mermaid-js.github.io/mermaid/#/
[fail-exit]: mermaidjs/mermaid.cli#77
    @timblair
    chrisfarms authored and timblair committed Nov 14, 2024
    Configuration menu
    Copy the full SHA
    d2ed7ea View commit details
    Browse the repository at this point in the history

  2. Add tabindex for fallback code view

    @timblair
    timblair committed Nov 14, 2024
    Configuration menu
    Copy the full SHA
    872e85c View commit details
    Browse the repository at this point in the history

  3. Fix Rubocop failures

    @timblair
    timblair committed Nov 14, 2024
    Configuration menu
    Copy the full SHA
    c851210 View commit details
    Browse the repository at this point in the history