Skip to content

Azure DevOps Wiki and Mermaid diagrams

Mermaid
Photo by Victoria Borodinova from Pexels

Mermaid is a Javascript based diagramming and charting tool that renders markdown like text definitions into SVG diagrams. It works little bit like PlantUML, but does not require any extensions to run. Rendering is done simply with JS library that produces embeddable SVG images. Azure DevOps have had the support for Mermaid diagrams since 2019 (cloud version only) and it is a great way to put diagrams into Wiki pages without external tools like Visio.

Creating the diagram

Mermaid code can be inserted directly into Wiki page inside :: mermaid ::: tags.

::: mermaid
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]
:::

The diagram can be reviewed by clicking the “Load diagram” button.

Mermaid syntax inside Wiki page
Mermaid syntax inside Wiki page

The above Mermaid code creates this kind of diagram into Wiki page

Mermaid diagram in Wiki page
Mermaid diagram in Wiki page

Restrictions

Azure DevOps currently supports only flow, sequence and gantt diagrams. There is a highly voted user voice that demands more diagram types, but it has been open for two years now. I think it is very unlikely that new diagram types will be supported in near future.

Mermaid diagrams cannot be placed into work items or used within comments. The syntax is only supported in Wiki pages. However you can add links to Wiki pages from work items and add diagrams that way.

The mermaid.live has a cool online editor for Mermaid diagrams and you can use it to develop the diagrams and copy-paste the code into Wiki page. By using the Markdown code you can also add unsupported diagram types like class and ER diagrams directly into Wiki page.