docs: add how-to guide for Mermaid diagramming tool

[AnneCYH]

• Have you updated CHANGELOG.md with relevant non-documentation file changes?
• Have you updated the documentation for this change?

---

[AnneCYH]

Hi @SecondSkoll ,

Could you give this an initial review to see if this matches your expectations for the standard workflow + approach task?
We will align the rest of the content based on your feedback / any concerns you may have with this structure.

Thanks.

p/s: I'll make sure the 2 checkboxes are acknowledged / ticked and get the rest of the tests passing.

[SecondSkoll]

Great work. I would like to see some advice on what to do for images in dark mode:

Which could be as simple as adding some CSS to set the background of pre.mermaid to white.

Otherwise I think this is good. I think it's possible we've got a more technical audience than this topic is aimed at - but I think with our efforts in CODA, having topics like this with a low barrier of entry is probably a good way to go.

[AnneCYH]

Great work. I would like to see some advice on what to do for images in dark mode:

Which could be as simple as adding some CSS to set the background of `pre.mermaid` to white.

Otherwise I think this is good. I think it's possible we've got a more technical audience than this topic is aimed at - but I think with our efforts in CODA, having topics like this with a low barrier of entry is probably a good way to go.

Hey @SecondSkoll ,

Interesting point.
When you mentioned 'more technical audience' I think it would be helpful to understand what they want to achieve with Mermaid and improve the docs / examples accordingly.

[AnneCYH]

these are from the Ubuntu color palette
avoiding white as it's a bit too jarring in dark mode.

[SecondSkoll]

if data-theme="auto", and your browser just detects dark mode, this overwrite doesn't work.

[medubelko]

Hi @AnneCYH, I think this is great. It'll make some of my engineers happy. :)

[AshleyCliff]

Section formatting and wording look good to me! (Per request to review from @medubelko)

[medubelko]

I'm approving this for its technical correctness, but I'm not certain how we want this to be used. I believe @SecondSkoll might have an answer.

We've written this as an opt-in guide for Mermaid, but as far as this is a template repo, the implementation is at cross-purposes because:

1. When a user duplicates the repo, the Mermaid config, including the stylesheet with Ubuntu branding, is already active. So if they follow the guide, there will be nothing for them to do.
2. We also render some Mermaid diagrams in the docs, so it's not a simple matter of disabling the extension.

If we wanted to make this a truly opt-in guide, I don't think we should enable the extension or include the CSS file. The only workaround for the docs I can think of is to insert images of the generated diagrams.

[AnneCYH]

Thanks @medubelko .

It's similar to the rest of the approaches / tools we are trying to document; they are optional.

I agree with what you said. Maybe this doc should just guide you on how to get it enabled but as you said, the settings should not be enabled by default. And attaching PNGs of the rendered diagrams to demonstrate how they would appear would avoid build failures because of Mermaid code.

[AnneCYH]

Note: library-related links are down at the moment; suggesting to skip those as 'blocking' issues if we want to merge.
Thanks.

[SecondSkoll]

if data-theme="auto", and your browser just detects dark mode, this overwrite doesn't work.

[SecondSkoll]

@medubelko raises a salient point. Part of this work is to make sure we continue to support these extensions over time, but we do want to ensure the starter pack itself is relatively minimal so it can be used as a template. This means there should probably be a separate project that is tightly linked to the starter pack, where we can link to the practical implementation of what we document here. I can't think of a really neat solution to this. I agree with using images for now.

[AnneCYH]

Hi @SecondSkoll , I don't know how to properly fix the CSS in a theme- mode-agnostic manner.
Could we set a background color regardless of the theme / mode for now? This way it renders clearly enough regardless of your browser / device settings.

Thanks.

[SecondSkoll]

Hi @SecondSkoll , I don't know how to properly fix the CSS in a theme- mode-agnostic manner. Could we set a background color regardless of the theme / mode for now? This way it renders clearly enough regardless of your browser / device settings.

Thanks.

Yep, that should be fine.

[AnneCYH]

Hi @medubelko and @SecondSkoll ,

I've addressed all the comments and updated the PR.

• Used images instead of 'live code' for Mermaid diagrams
• Set a background for the Mermaid CSS so it shows up properly in any color scheme / theme

Please do review and lemme know if I'm still missing anything else.

Thanks!

[AnneCYH]

Fixed the merge conflict, @SecondSkoll , thanks.

[SecondSkoll]

LGTM. I don't love using the asset manager, but the diagrams won't need to change as they're just examples of diagrams.