I like Mermaid but I find the rendered diagrams do not look at pretty as some of the other tools, so I set out to find out more on how the diagrams could be styled to look different. In this post, I summarise my findings and approach for styling sequence diagrams (the diagram that I want to use the most).

Themes and styles

Let’s start by taking a very simple sequence that we will use for styling:

sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Note right of John: This is the default
    Alice-)John: See you later!
    John->>John: Note changes

When rendered normally (using the default theme), it will probably look like this.

sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Note right of John: This is the default
    Alice-)John: See you later!
    John->>John: Note changes

Let’s look at what we can do with this.

Mermaid Diagrams and Front matter

Before we go any further, we need to understand a different concept of Mermaid diagrams. Mermaid allows us to provide front matter which is provided before the main diagram code. This is what adding front matter looks like:

---
title: A simple diagram
config:
  showSequenceNumbers: true
  theme: base
---
sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
...

The first bit that shows the title and configuration is the front matter and is like YAML. You start with `—-` and also end with `—-` before the diagram. Each line is a key-value pair, e.g., “title” is “A simple diagram”. For items that have sub-items, we just indent them with two spaces as in the next few lines of the front matter. In these lines, we basically set that `config.showSequenceNumbers` is `true`, and the `theme` is `base`. We will use this ability a lot in the next few sections.

Mermaid themes

The first thing to try is to see how things look with the different themes that Mermaid offers. Mermaid has 5 themes:

• Default
• Neutral: recommended for black and white print documents
• Dark: good for dark mode
• Forest: shades of green
• Base: the theme that can be modified and customised

The original diagram was rendered in `default` and the other themes are rendered below for comparison.

This already gives us a few more options, and I have to admit that I like neutral and base some of the other themes a bit more than the default. The way to change the theme is as shown in the previous sample by adding theme under config:

---
title: A simple diagram
config:
  showSequenceNumbers: true
  theme: base
---
sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
...

We will try to style further but note that only the base theme can be modified or customised.

Changing some of the colours

Let’s change it up for some of the colours. We set the following colours to soften the dark text and lines a bit to lighter shades of grey.

• primaryColor: “#d0d0d0” – this is the primary colour used as background in nodes
• signalColor: “#808080” – this changes the colour of the signals/ arrow lines
• signalTextColor: “#404040” – this changs the colour of the text on the signals

We set this as the front matter before the sequence diagram and the resulting diagram is shown below.

---
config:
  theme: base
  themeVariables:
    primaryColor: "#d0d0d0"
    signalColor: "#909090"
    signalTextColor: "#808080"
---
sequenceDiagram
    participant Alice
    participant John
...

---
config:
  theme: base
  themeVariables:
    primaryColor: "#d0d0d0"
    signalColor: "#909090"
    signalTextColor: "#808080"
---
sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Note right of John: This is the base
    Alice-)John: See you later!
    John->>John: Note changes

Look at this table for the things you can set in this way.

Changing the arrow for self items

I had to find this from the code, but there is an undocumented configuration that does not render the arrow as a loop but instead as right angle lines. This uses a config item called rightAngles that you set to true and you can see the effect below. In this one, we also added a line to change the fontFamily.

---
config:
  rightAngles: true
  theme: base
  themeVariables:
    fontFamily: "Helvetica, Arial, Calibri"
    primaryColor: "#d0d0d0"
    signalColor: "#909090"
    signalTextColor: "#808080"
---
sequenceDiagram
    participant Alice
    participant John
...

---
config:
  rightAngles: true
  theme: base
  themeVariables:
    fontFamily: "Helvetica, Arial, Calibri"
    primaryColor: "#d0d0d0"
    signalColor: "#909090"
    signalTextColor: "#808080"
---
sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Note right of John: This is the base
    Alice-)John: See you later!
    John->>John: Note changes

Styling the CSS

Mermaid uses CSS for styling, so some things can be set directly using CSS. In the next post, we will get into styling the CSS for finer grain control on how our diagrams look.

References

If you want to find out more, here are the pages that guided me along:

• Mermaid’s link for themes: https://mermaid.js.org/config/theming.html
• Adding Configuration in Frontmatter: https://mermaid.js.org/config/configuration.html
• Styling and configuration for sequence diagrams: https://mermaid.js.org/syntax/sequenceDiagram.html#configuration

Feel free to share the post (you can start a conversation or tag me as @onghu on Twitter or on Mastodon as @onghu@ruby.social ) or leave a comment below.