Create diagrams as code using Mermaid

Diagrams help users quickly understand and visualize complex ideas, but they can easily become outdated and difficult to maintain. Creating diagrams as code solves this by keeping them alongside the software source, making updates and reviews simpler.

Mermaid is a popular choice that allows diagrams to be created, maintained, and updated directly in the documentation. This guide explains how to set up the sphinxcontrib-mermaid extension and use Mermaid diagrams in your documentation, with examples included.

Note

While there are many other tools and/or approaches for creating diagrams in visualizations in your documentation (e.g. C4 model, Dia, PlantUML, Structurizr, etc), we only provide support for sphinxcontrib-mermaid in the starter pack.

Installation and setup

First, add the “sphinxcontrib-mermaid” extension to requirements.txt so that it’s installed as part of your Sphinx project dependencies:

canonical-sphinx[full]
packaging
sphinxcontrib-svg2pdfconverter[CairoSVG]
sphinx-last-updated-by-git
sphinx-sitemap
sphinxcontrib-mermaid

Then add “sphinxcontrib.mermaid” in the “extensions” list in conf.py:

extensions = [
    [...]
    "sphinxcontrib.mermaid",
]

You are now ready embed Mermaid diagrams and visualization in your documentation using the mermaid directive.

Optional configuration

You can further configure Mermaid’s default settings in your project’s conf.py, such as specifying the image output format (e.g., “png”, “raw”), enabling zoom on diagrams, or pinning the Mermaid version used for rendering.

See Mermaid configuration values for more information.

Add a new diagram

Use the mermaid directive to embed a Mermaid diagram into your documentation. You start by declaring the type of diagram (e.g. “flowchart”, “sequenceDiagram”, “timeline”, etc), followed by definition and contents. It is also possible to specify additional configuration or custom styles, depending on the diagram type.

Some examples will be covered below.

See also

See the Mermaid - Diagram syntax reference for details on the syntax and customization options for each diagram type.

Flowchart diagram with default settings

The left-to-right flowchart below uses the default Mermaid settings.

https://assets.ubuntu.com/v1/34c7105c-screenshot_from_2025_10_13_15_05_56.png 
```{mermaid}
flowchart LR
    A([New PR])
    B[Needs review]
    C{Review approved?}
    D{Merge conflicts?}
    E[Needs work]
    F[Needs CI]
    G{Passed testing?}
    H[Ready for merge]
    I[(PR merged)]
    J{Comments addressed?}
    K[(PR closed)]

    A --> B
    B --> C
    C -- no --> E
    C -- yes --> D
    D -- yes --> E
    D -- no --> F
    F --> G
    G -- yes --> H
    G -- no --> E
    H --> I
    E --> J
    J -- yes --> B
    J -- no --> K
```

.. mermaid::

   flowchart LR
       A([New PR])
       B[Needs review]
       C{Review approved?}
       D{Merge conflicts?}
       E[Needs work]
       F[Needs CI]
       G{Passed testing?}
       H[Ready for merge]
       I[(PR merged)]
       J{Comments addressed?}
       K[(PR closed)]
   
       A --> B
       B --> C
       C -- no --> E
       C -- yes --> D
       D -- yes --> E
       D -- no --> F
       F --> G
       G -- yes --> H
       G -- no --> E
       H --> I
       E --> J
       J -- yes --> B
       J -- no --> K

Timeline diagram with pre-defined theme

The timeline diagram below uses a pre-defined Mermaid theme.

https://assets.ubuntu.com/v1/24895eed-screenshot_from_2025_10_13_15_06_35.png 
```{mermaid}
%%{init: {"theme":"forest"}}%%
timeline
    title Ubuntu recent releases

    2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
    2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
    2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
    2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
    2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
    2025 : 25.04 (Plucky Puffin)
```

.. mermaid::

   %%{init: {"theme":"forest"}}%%
   timeline
       title Ubuntu recent releases

       2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla)
       2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri)   
       2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu)
       2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur)
       2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole)
       2025 : 25.04 (Plucky Puffin)

Sequence diagram with global custom CSS

The sequence diagram below has custom styling applied using a global CSS file. A global CSS file enables the styles to be easily applied to all sequence diagrams, based on the classes defined in your stylesheet. You can also use the global CSS file to customize the diagrams in dark mode.

https://assets.ubuntu.com/v1/a7eb0fcf-screenshot_from_2025_10_13_15_08_06.png

First, create a Mermaid stylesheet in the _static directory and customize it as needed. For example, mermaid-sequence.css.

Then, enable custom stylesheets in conf.py. Uncomment this line so Sphinx can use local stylesheets:

conf.py
html_static_path = ["_static"]

Link to your custom Mermaid stylesheet:

conf.py
html_css_files = [
    "mermaid-sequence.css",
]

Here’s an example stylesheet that changes the default typefaces and colors of Mermaid components. It also sets a solid background color for all Mermaid diagrams.

mermaid-sequence.css
.actor {
  stroke: #eb6536 !important;
  stroke-width: 2;
  fill: #f5b29b !important;
}

text.actor {
  fill: black;
  stroke: none;
  font-family: Helvetica;
}

.actor-line {
  stroke: #77216f;
}

.mermaid {
    background-color: #f0f0f0;
    border: 1px solid #ccc;
    border-radius: 6px;
    padding: 0.5em;
}

```{mermaid}
sequenceDiagram
    participant User
    participant Snap as snapd (Client)
    participant Store as Snap Store
    participant System

    User->>Snap: snap install hello
    Snap->>Store: Request snap info and download
    Store-->>Snap: Return snap package
    Snap->>System: Install and mount snap
    System-->>Snap: Installation result
    Snap-->>User: Confirm snap is installed
```

.. mermaid::

   sequenceDiagram
       participant User
       participant Snap as snapd (Client)
       participant Store as Snap Store
       participant System
   
       User->>Snap: snap install hello
       Snap->>Store: Request snap info and download
       Store-->>Snap: Return snap package
       Snap->>System: Install and mount snap
       System-->>Snap: Installation result
       Snap-->>User: Confirm snap is installed

State diagram with image-specific styles

The state diagram below has image-specific custom styling applied using the classDef keyword.

https://assets.ubuntu.com/v1/dd4fb237-screenshot_from_2025_10_13_15_08_51.png 
```{mermaid}
stateDiagram-v2
    classDef review fill:#FCE83A
    classDef approved  fill:#2DCCFF
    classDef published fill:#56F000
    classDef archived fill:#7B8089

    [*] --> Draft
    Draft --> Review : submit for review
    Review --> Draft : changes requested
    Review --> Approved : review passed
    Approved --> Build : trigger build
    Build --> Published : build success
    Build --> Draft : build failed
    Published --> Archived : old version

    class Review review
    class Approved approved
    class Published published
    class Archived archived
```

.. mermaid::

    stateDiagram-v2
        classDef review fill:#FCE83A
        classDef approved  fill:#2DCCFF
        classDef published fill:#56F000
        classDef archived fill:#7B8089
    
        [*] --> Draft
        Draft --> Review : submit for review
        Review --> Draft : changes requested
        Review --> Approved : review passed
        Approved --> Build : trigger build
        Build --> Published : build success
        Build --> Draft : build failed
        Published --> Archived : old version
    
        class Review review
        class Approved approved
        class Published published
        class Archived archived

Projects using Mermaid

Here are some Canonical projects that use Mermaid for diagramming in their documentation: