kalmstrom.com Business Solutions
Mermaid
Web Part
User Guide
Version 0.2.0.8  ·  SharePoint 2013-Online, modern and classic pages
Published November 2026
Contents
1Introduction
5
What you get
5
1.1What is Mermaid?
6
1.2Why text-based diagrams?
6
1.3When NOT to use Mermaid
8
1.4The Mermaid ecosystem
9
1.5What the Mermaid Web Part adds
10
1.6Web Part features summary
11
1.7Supported diagram types
12
2Editions and installation
13
2.1Editions and packages
13
2.2Installing with the Installer
14
2.3Installing the modern package (.sppkg)
16
2.4Installing the classic package (.wsp)
18
2.5Installing with the PowerShell script (.ps1)
21
2.6Trial, registration and support
23
3Getting started
25
3.1Adding the web part to a page
25
3.2The default diagram
26
3.3How diagrams are saved
27
3.4Editing an existing diagram
28
3.5Permissions
29
3.6Mobile and tablet use
29
4The code editor
30
4.1Editor layout
30
4.2Writing Mermaid code
31
4.3Live preview behaviour
32
4.4Keyboard shortcuts in the editor
33
4.5Saving and discarding changes
33
4.6Version and instance information
33
5Tools
34
5.1Edit in Live
34
5.2Snippets
35
5.3Add Click Handler
36
5.4Right-click context menu (preview panel)
37
5.5Theme picker
38
5.6Charts from a SharePoint list
39
6Example library
42
6.1Opening the examples section
42
6.2Featured examples
44
6.3Additional examples by type
45
6.4Solution showcase
46
7Diagram type reference
47
7.1Flow and process diagrams
48
7.2Data and relationship diagrams
50
7.3Architecture diagrams
51
7.4Project planning diagrams
52
7.5Data visualisation
54
7.6Other types
57
8Troubleshooting
59
8.1Common issues and solutions
59
8.2Permissions
63
8.3Known limitations
63
8.4Mobile and tablet use
64
Quick Reference
65
Glossary
67
Mermaid syntax
67
Editor and web part
69
SharePoint
70
Rendering
71
Index
72
Index (continued)
73

Chapter 1Introduction

The Mermaid Web Part brings professional, text-based diagramming to SharePoint pages, modern and classic, in SharePoint Online and on-premises.

What you get

Diagrams that stay current

Process charts, org charts and timelines are text on the page. Changing a step takes one line, not a new screenshot from Visio. Charts can also be drawn from a SharePoint list and update themselves when the list changes.

No drawing skills needed

Start from one of 47 ready-made examples and change the words. The preview shows the result as you type.

Clickable intranet maps

Any box can link to a site, a document or a list, so a diagram becomes the way into your intranet.

Nothing extra to run

Works in SharePoint Online and on-premises, on modern and classic pages. Diagrams are kept in the site itself; no external service or database is needed to show them.

The rest of this chapter explains what Mermaid is, when text-based diagrams beat drawing tools, and what the web part adds on top of the Mermaid engine. To start right away, go to Chapter 3.

See it in 2 minutes: the demo video shows an editor adding the web part, picking a ready-made example and changing it, without writing any Mermaid code.

1.1 What is Mermaid?

Mermaid is an open-source JavaScript library that converts plain text into SVG diagrams directly in the browser. It was created in 2014 by Knut Sveidqvist and has since grown into one of the most widely adopted diagramming systems in the software industry. Major platforms — GitHub, GitLab, Confluence, Notion, and Azure DevOps — all render Mermaid natively in their Markdown editors.

The core idea is simple: instead of drawing a diagram by dragging boxes and arrows, you describe the diagram in a concise notation, and Mermaid renders it. A flowchart that would take ten minutes to arrange by hand can be written in seconds:

graph TD
    A[Customer Request] --> B{In Stock?}
    B -->|Yes| C[Process Order]
    B -->|No| D[Back Order]

This notation is instantly readable by a human, can be stored in any text file, and produces a clean, consistently styled vector diagram every time it is rendered.

Mermaid text parse Mermaid Engine JavaScript library render SVG output Start OK? display SharePoint page visible to all users

1.2 Why text-based diagrams?

Most organisations still use visual drawing tools — Microsoft Visio, PowerPoint SmartArt, Lucidchart, or browser-based alternatives — to create diagrams. These tools have well-known limitations that text-based approaches solve directly.

Consistent style, automatically

In drawing tools, every person who edits a diagram can change fonts, colours, box sizes, and spacing. Mermaid applies a consistent visual theme to every diagram, every time, with no manual alignment effort.

Easy to update

Adding a new step to a Visio flowchart requires moving every downstream box to make room. In Mermaid you add one line of text and the layout recalculates automatically.

Version control friendly

Because Mermaid diagrams are plain text, they can be stored in source control, diffed line by line, and reviewed in pull requests — impossible with binary drawing files.

No software licence required

Mermaid runs in any browser, free of charge. Viewers do not need Visio, Lucidchart, or any other installed tool to see a rendered diagram.

Lives where the content lives

A Mermaid diagram is stored as text alongside the page it illustrates. It does not require export, file attachment, or a separate link to an external system.

Accessible output

Mermaid renders SVG, which is natively accessible. Accessibility titles and descriptions can be added directly in the code with accTitle and accDescr directives.

Traditional drawing tools Mermaid text-based ✗ Manual layout — drag every box and arrow ✓ Auto-layout — engine positions all elements ✗ Inconsistent styles per author ✓ Uniform theme applied automatically ✗ Binary files — no diff, no version control ✓ Plain text — diffable, stored with content ✗ Requires Visio / Lucidchart licence ✓ Free, open-source, runs in any browser ✗ Adding a step = rearrange everything ✓ Adding a step = add one line of text

1.3 When NOT to use Mermaid

Mermaid is excellent for structured, logic-driven diagrams. It is a less natural fit when:

1.4 The Mermaid ecosystem

Because Mermaid is open-source and widely adopted, a large ecosystem has grown around it:

ResourceDescription
Mermaid Live Editor
mermaid.live
Official online editor with instant preview, theme selector, PNG/SVG export, and shareable diagram URLs. The Mermaid Web Part has a built-in link to open any diagram there.
GitHub Mermaid code blocks in Markdown files, issues, and pull request descriptions are rendered automatically. Writing a diagram in the web part produces code that is immediately usable in GitHub documentation.
Confluence Atlassian Confluence supports Mermaid natively in the Confluence Cloud editor. Teams who use both SharePoint and Confluence can share the same diagram code between platforms.
VS Code Multiple Mermaid extensions for Visual Studio Code provide live preview in the editor sidebar. Developers can write diagrams in their IDE and paste them directly into the web part.
Documentation tools MkDocs, Docusaurus, Hugo, and Jekyll all have Mermaid plugins. Diagrams written for these tools work unchanged in the Mermaid Web Part.

1.5 What the Mermaid Web Part adds

The Mermaid engine is a JavaScript library. Integrating it into a SharePoint web part requires solving several additional problems that the raw library does not address:

1.6 Web Part features summary

Live code editor

Side-by-side editor and live preview. Changes are reflected within 500 ms of typing.

47 example diagrams

15 featured examples plus 32 more, grouped by type. One click loads an example into the editor.

Code snippets

Insert shapes, link styles, themes, and click handlers at the cursor from a categorised menu.

Click-through nodes

A guided form generates Mermaid click syntax for any diagram node with no manual coding.

Mermaid Live integration

Open any diagram in the official Live Editor for advanced editing, then paste code back.

Right-click context menu

Right-click any preview node to add a link or jump to its definition in the code editor.

Charts from a SharePoint list

Org chart, gantt, pie, bar, line, treemap or kanban from the items of a list on the site, kept in sync if you want.

1.7 Supported diagram types

The web part supports these 20 diagram types of the Mermaid engine (version 11.12); newer beta types such as packet-beta and radar-beta also render:

TypeKeyword
Flowchartgraph TD / flowchart
Sequence diagramsequenceDiagram
Class diagramclassDiagram
State diagramstateDiagram-v2
Entity RelationshiperDiagram
Gantt chartgantt
Git graphgitGraph
Mindmapmindmap
Timelinetimeline
User journeyjourney
TypeKeyword
Architecture diagramarchitecture-beta
C4 diagramC4Context
Pie chartpie
Sankey diagramsankey-beta
XY chartxychart-beta
Quadrant chartquadrantChart
Kanban boardkanban
Treemaptreemap-beta
Requirement diagramrequirementDiagram
Block diagramblock-beta
Note: Types marked -beta are provided by the Mermaid engine in preview status and may change in future versions of the library.

Chapter 2Editions and installation

2.1 Editions and packages

The Mermaid Web Part comes in four different packages. The editor and the diagrams are the same in all of them; only the installation differs.

SharePointPackageHow the administrator installs it
SharePoint Online (modern pages)MM_SPFX_OnLine_<version>.sppkgUpload to the tenant or site collection App Catalog, then add Mermaid Web Part to a modern page.
SharePoint 2019 / Subscription Edition (modern pages)MM_SPFX_OnPrem_<version>.sppkgUpload to the on-premises App Catalog, then add the web part to a modern page.
SharePoint 2013 – SE, classic pagesMM_Sand_<version>.wspUpload to the site collection Solution Gallery and activate it twice (2.4); then add the diagram to a wiki page (3.1).
All of the aboveInstall-MermaidWebPart.ps1A PowerShell installer that installs any of the three packages above, modern or classic, for you (2.2).

2.2 Installing with the Installer

The Installer, Install-MermaidWebPart.ps1, is the easiest way to install Mermaid. It is one PowerShell script with a window, and it installs both the modern and the classic web part. To install manually instead, refer to 2.3 — 2.5.

  1. Right-click Install-MermaidWebPart.ps1 and open it in PowerShell, or press F5 in the PowerShell ISE. The installer window opens.
  2. Choose the package: SharePoint Online, SharePoint 2019 / SE or Classic sandboxed (.wsp).
  3. Fill in where it goes: the App Catalog site for the two .sppkg packages, or the site for the .wsp. SharePoint Online also needs the app id of your own Entra app registration for PnP PowerShell.
  4. Click Test (read only) to check the package and the sign-in. Then click Install. Tick What-if first if you want to see what would happen without changing anything.
The Mermaid web part installer window: package choice, App Catalog site, steps with their state, and the log
The installer during a SharePoint Online install: the package is read, the sign-in is done and the app is being published.

What you need: for SharePoint Online, the SharePoint Administrator role; for SharePoint 2019 and Subscription Edition, site collection administrator of the App Catalog site, and Windows PowerShell 5.1 (the installer adds the PnP PowerShell module it needs when it is missing); for the .wsp, site collection administrator of the site, run on a SharePoint server. Without a window, for example in a scheduled task, run it with parameters, for example .\Install-MermaidWebPart.ps1 -Action Install -Kind Online -CatalogUrl https://contoso.sharepoint.com/sites/appcatalog -ClientId <app id> -NoUI $true.

2.3 Installing the modern package (.sppkg)

Install once and every editor can use it. These steps are for the SPFx packages; the Installer can do them for you (2.2).

Install

  1. Open your App Catalog (in SharePoint Online: SharePoint admin center >More features >Apps, then Apps for SharePoint).
  2. Click Upload, choose the .sppkg file and click OK.
  3. SharePoint asks how to make the app available. Choose Only enable this app if site owners should add it themselves (step 4), or Enable this app and add it to all sites to put the Mermaid web part in the toolbox of every site at once. Then click Enable app. (SharePoint 2019 and Subscription Edition ask the same thing with the checkbox Make this solution available to all sites in the organization and the button Deploy.)
The Enable app panel after uploading the Mermaid package, with the choices Only enable this app and Enable this app and add it to all sites
Step 3: the choice SharePoint Online offers after the upload.
  1. If you didn't add it to all sites, a site owner adds it under Site contents >New >App >Mermaid web part.

Upgrade

Upload the new .sppkg to the App Catalog and replace the old one. All sites get the new version; the diagrams are not touched, because they live in each site's Site Assets library.

Remove

Delete the app from the App Catalog, and from Site contents in sites where it was added. Pages can then no longer show the diagrams. The diagram files (Mermaid_*.txt in Site Assets) stay, so a reinstall shows the same diagrams again.

2.4 Installing the classic package (.wsp)

Use MM_Sand_<version>.wsp (or MM_Sand_<version>Premium.wsp) for classic pages in SharePoint 2013, 2016, 2019 and Subscription Edition. It is a sandboxed solution: a site collection administrator installs it, with no farm or server access. It is installed per site collection.

Install

  1. Sign in as a site collection administrator and open the top site of the site collection.
  2. Go to Site settings >Web Designer Galleries >Solutions.
  3. Click Upload Solution, browse to the .wsp file and click OK.
  4. In the dialog that opens, click Activate. This activates the solution.
  5. Go to Site settings >Site Collection Administration >Site collection features, find Mermaid Webpart and make sure it shows Active; if it shows an Activate button, click it. This second activation turns the web part on in the site.
The Solutions gallery with Upload Solution, Activate and Deactivate in the ribbon
Step 2: the Solutions gallery and its ribbon.
The Add a solution dialog with the Mermaid .wsp file chosen
Step 3: the .wsp chosen in Add a solution.
The solution dialog after the upload, with the Activate button and the trust warning
Step 4: click Activate in the solution dialog.
Site collection features with Mermaid Webpart 0.1.7.0 shown as Active
Step 5: Mermaid Webpart is Active in Site collection features.

Activating the solution puts the Mermaid script (MM.js) in the Site Assets library and loads it for every page in the site. If the site has no Site Assets library, it is created. Then add a diagram to a page as in 3.1.

Sandboxed code must be allowed. On SharePoint 2013 and 2016 the farm must run the Microsoft SharePoint Foundation Sandboxed Code Service; if Activate is greyed out, ask the farm administrator to start it. The Mermaid solution contains no server code, only a script, so it also activates where server code in sandboxed solutions is blocked.

Upgrade

In Solutions, select the old Mermaid solution and click Deactivate, then upload the new .wsp and activate it twice, as when installing. The diagrams are not touched, because they are kept in Site Assets (3.3).

Remove

Deactivate the solution in Solutions, then delete it. Pages stop showing the diagrams; the diagram files (Mermaid_*.txt in Site Assets) stay, so a reinstall shows them again.

2.5 Installing with the PowerShell script (.ps1)

The file Install-MermaidWebPart.ps1 can be used to install the Mermaid web part in modern as well as classic SharePoint pages in both Online and On-Premises SharePoint.

Administrators who install on many sites can also do the same steps with PowerShell commands. Replace the file name, version and site address with your own.

Three ways to install with PowerShell: classic .wsp with Add-SPUserSolution and Install-SPUserSolution, SharePoint Online .sppkg with Connect-PnPOnline and Add-PnPApp, on-premises .sppkg with Add-PnPApp and Install-PnPApp
The PowerShell commands for each package.

Classic package (.wsp), SharePoint Management Shell on a SharePoint server:

Add-SPUserSolution -LiteralPath "C:\Install\MM_Sand_<version>.wsp" -Site "https://intranet/sites/Team"
Install-SPUserSolution -Identity "MM_Sand_<version>.wsp" -Site "https://intranet/sites/Team"

To upgrade, add the new file and run Update-SPUserSolution -Identity "MM_Sand_<old>.wsp" -ToSolution "MM_Sand_<new>.wsp" -Site .... To remove, run Uninstall-SPUserSolution and then Remove-SPUserSolution with the same -Identity and -Site.

SharePoint Online (.sppkg), PnP PowerShell:

Connect-PnPOnline -Url "https://contoso-admin.sharepoint.com" -Interactive -ClientId "<your app id>"
Add-PnPApp -Path "C:\Install\MM_SPFX_OnLine_<version>.sppkg" -Scope Tenant -Publish -Overwrite

SharePoint 2019 / Subscription Edition (.sppkg), PnP PowerShell: connect to the site of your on-premises App Catalog and run the same Add-PnPApp ... -Publish -Overwrite with the MM_SPFX_OnPrem file. Then add the app to a site with Install-PnPApp -Identity <app id>, or let site owners add it from Site contents (2.3).

2.6 Trial, registration and support

You may evaluate the Mermaid Web Part for 30 days with full functionality and without cost.

If you want to continue using the Mermaid Web Part after the trial period, you must start a subscription. We supply a Premium version of the Mermaid Web Part, which does not require registration at all, but organizations who select the Standard plan must register their installations.

Standard subscribers are given a registration key, which allows the organization to continue using the Mermaid Web Part for the duration of the subscription year.

Register the Mermaid Web Part

  1. Open a page with a Mermaid diagram. When the trial has ended, the registration dialog opens over the diagram.
  2. Enter an e-mail address with your company or organization domain, and the registration key you have received from kalmstrom.com Business Solutions.
  3. Click Register.

The person who registers the Mermaid Web Part should have at least Owner permission on the site. Each site collection where the Mermaid Web Part is used needs to be registered. The registration key continues to work for as long as the organization is a kalmstrom.com subscriber.

Support

If you have any kind of problem or question about the Mermaid Web Part, there are several ways of contacting us:

ChannelAddressFor
E-mailsupport@kalmstrom.comTechnical issues
sales@kalmstrom.comSubscription and general issues
finance@kalmstrom.comInvoices, payments, quotations
Telephone+46 739 206 106
Teamspeter@kalmstrom.comChats, remote sessions
Zoompeter@kalmstrom.comChats, remote sessions

Chapter 3Getting started

This chapter explains how to add the Mermaid Web Part to a SharePoint page and what you see when it first loads.

3.1 Adding the web part to a page

An administrator installs the web part once (see 2.2, or 2.3 and 2.4). After that, anyone who can edit a page can add it.

On a modern page (SharePoint Online, 2019, Subscription Edition)

  1. Open the page and click Edit at the top right.
  2. Point at the place where the diagram should go and click the round + button.
  3. Type Mermaid in the search box of the toolbox and click the Mermaid web part (group Advanced).
  4. The web part shows a default diagram at once.
  5. Click Republish (or Publish) so visitors see the new web part.

On a classic page (.wsp package, see 2.4)

  1. Open a wiki page (for example a new page in Site Pages) and click Edit.
  2. Put the cursor where the diagram should go, then choose Format Text >Edit Source in the ribbon.
  3. Type <div id="MMMain"></div> at that place and click OK.
  4. Save the page. The default diagram appears where the line is.
Tip: On modern pages you can add more than one Mermaid Web Part to the same page; each keeps its own diagram. On a classic page there is one diagram per page.

3.2 The default diagram

When the web part is first placed on a page, it displays a built-in example that demonstrates several Mermaid features in one diagram: coloured nodes, styled links, and clickable nodes that open other pages.

The default diagram is a site architecture chart showing:

The default Mermaid diagram on a SharePoint Online page: Home, Projects, Admin Center, Project 1 and Project 2
The default diagram, as visitors see it on a modern page.

You can replace this diagram at any time by opening the code editor (see Chapter 4).

3.3 How diagrams are saved

When you click OK in the editor, the Mermaid code is saved at once. You do not need to save the page for the diagram to be kept. Each web part instance keeps its code in its own small text file in the site's Site Assets library, named Mermaid_<instance ID>.txt. No list or database is needed.

For administrators: The diagrams are the Mermaid_*.txt files in the Site Assets library. Back them up and restore them with that library. Do not delete them: a web part whose file is gone shows the default diagram again. People who edit diagrams need permission to add and change files in Site Assets.

3.4 Editing an existing diagram

To change a diagram that is already on the page:

1. Edit mode put page in edit mode 2. Open sliders or gear on the web part 3. Edit code write Mermaid syntax 4. Click OK diagram re-renders 5. Done saved at once, visible to all
  1. Put the page in edit mode (Edit at the top right of a modern page; the ribbon on a classic page).
  2. Open the editor. On a modern page, click next to the diagram to select the web part, then click the Edit properties button (the sliders icon) in the small toolbar above it. On a classic page, click the gear icon at the top right of the diagram.
  3. The Mermaid Code Editor dialog opens (see Chapter 4).
A modern SharePoint page in edit mode with the Mermaid web part selected and its toolbar above the diagram
Edit mode on a modern page. The second icon in the toolbar above the diagram (sliders) opens the Mermaid editor.
  1. Make your changes and click OK. The diagram is saved and redrawn at once.
  2. Leave edit mode as usual. You don't need to republish the page for a diagram change.

3.5 Permissions

Access to the Mermaid Web Part is controlled entirely by SharePoint's standard page permissions. No special web part-level permissions exist.

RoleRequired permissionCan do
Administrator SharePoint admin / App Catalog owner (modern); site collection admin (classic) Install the package (see 2.2, or 2.3 and 2.4). Can also do everything an editor can.
Page editor Contribute or Design Add the web part to a page, open the code editor, write and save diagrams, publish changes.
Visitor Read View the rendered diagram and click any interactive nodes. Cannot open the editor.

3.6 Mobile and tablet use

The web part behaves differently in view mode compared to edit mode on small screens:

A wide Mermaid flowchart on a SharePoint page, drawn at full size with a horizontal scrollbar below it
A diagram wider than the web part: it keeps its full size, and a scrollbar shows the rest.

Chapter 4The code editor

The Mermaid Code Editor is the main dialog for writing and previewing diagram code. It opens over the page with two tabs at the top: ✏️ My own code, where you write the code with a live preview beside it, and 📊 From a list, which makes a chart from a SharePoint list (5.6). Close it with OK to save, or with Cancel or the × in the title bar to discard.

4.1 Editor layout

Code panel (left)

A text editor pre-loaded with the current diagram code. Supports Tab for indentation (inserts two spaces). Spell-check is disabled so Mermaid keywords are not highlighted as errors.

Live preview (right)

Automatically re-renders the diagram 500 ms after you stop typing. If the code contains a syntax error, the preview turns red and names the error.

A splitter bar between the two panels can be dragged left or right. Each panel has a minimum width of 250 px.

The Mermaid Code Editor: the My own code and From a list tabs at the top, the toolbar, code on the left and the live preview on the right
The Mermaid Code Editor, tab My own code: toolbar on top, code left, live preview right, Cancel and OK at the bottom.

4.2 Writing Mermaid code

Mermaid code starts with a diagram type declaration, followed by the content specific to that type. For example, a basic flowchart:

graph TD
    A[Start] --> B{Ready?}
    B -->|Yes| C[Continue]
    B -->|No| D[Wait]

Each diagram type has its own syntax. The built-in examples (Chapter 6) demonstrate the most common patterns. For a full language reference visit the official Mermaid documentation at mermaid.js.org.

4.3 Live preview behaviour

The preview updates automatically while you type. There is a 500 ms debounce delay, so the engine waits until you pause before re-rendering. This prevents unnecessary re-renders on every keystroke.

When the code panel is empty, the preview displays the placeholder text "Enter code to see the preview..."

When the code contains a syntax error, the preview turns red and shows the engine's message with the line number. The error does not affect the saved diagram — the diagram on the page stays as it was until you save code that works.

The code editor with an unfinished arrow: the preview panel turns red and reads Mermaid syntax error, Parse error on line 3
An unfinished arrow (B -->): the preview turns red and names line 3. Fix the code and the diagram comes back.

4.4 Keyboard shortcuts in the editor

KeyAction
TabInsert two spaces at the cursor (does not change keyboard focus)
Ctrl+ZUndo (browser native)
Ctrl+YRedo (browser native)
Ctrl+ASelect all code (browser native)
Ctrl+C / VCopy / Paste (browser native)

4.5 Saving and discarding changes

The toolbar at the bottom of the editor contains two controls:

Remember: Clicking OK saves the diagram straight away (to the Site Assets library, see 3.3). Closing the dialog keeps the old diagram, unless you picked an example (6.1): that is saved at once.

4.6 Version and instance information

A grey information row at the bottom of the editor shows:

Chapter 5Tools

The editor toolbar contains a Theme picker (5.5) and three tools that help you write Mermaid code faster and add interactivity to diagrams. A right-click context menu on the preview panel provides additional node-level actions. The second tab of the editor, From a list, makes a chart from a SharePoint list without any code (5.6).

Mermaid Live Editor mermaid.live  (browser tab) ✏ Edit in Live — opens code in browser 📋 Snippets click → inserts at cursor 🔗 Add Click generates click syntax Code Editor Tab = 2 spaces · Ctrl+Z undo auto-renders after 500 ms Live Preview Node A Node B Node C right-click a node to open context menu 🔗 Add Link 📝 Select Code

5.1 Edit in Live

The ✏️ Edit in Live link opens the current diagram code in the Mermaid Live Editor in a new browser tab. The Mermaid Live Editor is the official online tool provided by the Mermaid project and offers additional features such as:

After editing in the Live Editor, copy the code from there and paste it back into the web part editor. Changes made in the Live Editor are not automatically synchronised back to SharePoint.

5.2 Snippets

The 📋 Snippets button opens a categorised drop-down menu of reusable code fragments. Clicking a snippet inserts it at the current cursor position in the editor.

Snippet categories:

CategoryContents
Quick StartComplete starter templates for Flowchart, Sequence, Gantt, Class, and State diagrams
Node ShapesIndividual shape declarations: Rectangle, Rounded, Circle, Diamond, Hexagon, Database, Subprocess, Trapezoid
Link StylesArrow variants: Solid, Dashed, Thick, Labeled, Bidirectional, No Arrow
StylingClass definitions, link style rules, inline node styles, subgraph wrapper
InteractiveClick handler, callback function, sequence actor link, accessibility labels
ThemesYAML front-matter blocks for Custom Colors, Hand-Drawn, Dark, and Forest themes
The Snippets menu open in the Mermaid Code Editor, showing the Quick Start and Node Shapes groups
The Snippets menu. Click an item to insert it at the cursor.
Tip: Place the cursor at the end of the diagram before opening Snippets — the snippet is inserted exactly at the cursor position, so you control where it appears in the code.

5.3 Add Click Handler

The 🔗 Add Click button opens a dialog that generates the Mermaid click syntax for making a diagram node into a hyperlink.

Fields in the dialog

FieldDescription
Node IDDrop-down list of all node IDs detected in the current diagram. Select the node you want to make clickable.
Target URLThe destination URL. Click 📌 Use Current Site URL to prefill with the current SharePoint site URL.
TooltipText shown when the user hovers over the node. Defaults to "Click to open" if left empty.
Open in New TabWhen checked (default), the link opens in a new browser tab (_blank). Uncheck for same-tab navigation.

The Preview area at the bottom of the dialog shows the exact Mermaid syntax that will be inserted, updating live as you fill in the fields. Clicking Insert Click Handler appends the generated line to the editor at the cursor position and closes the dialog. Example: click A "https://intranet.example.com/projects" "Go to Projects" _blank

The Add Click Handler dialog over the Mermaid Code Editor: Node ID, Target URL, Use Current Site URL, Tooltip, Open in New Tab and a preview of the generated line
The Add Click Handler dialog. Pick a box, type or paste the address, and click Insert Click Handler.

5.4 Right-click context menu (preview panel)

Right-clicking a node in the live preview panel opens a small context menu with two actions:

ActionWhat it does
🔗 Add Link Opens the Add Click Handler dialog (section 5.3) with the right-clicked node pre-selected in the Node ID drop-down.
📝 Select Code Locates the first occurrence of the node's definition in the code editor and selects the matching text, making it easy to jump to and edit that node.
LIVE PREVIEW Home Projects Admin ▷ 🔗 Add Link to Admin 📝 Select Code Right-click on the "Admin" node to open the context menu
Note: The context menu only appears when right-clicking directly on a diagram node. Right-clicking on the background of the preview panel has no effect.

5.5 Theme picker

The Theme drop-down in the toolbar applies one of Mermaid's built-in color themes to the diagram: default, neutral, dark, forest or base.

Choosing a theme writes a small configuration block at the top of the diagram code:

---
config:
  theme: dark
---
graph TD
    A --> B

Because the theme is stored in the code itself, it is saved with the diagram and never affects other diagrams on the same page. You can also edit or remove the block by hand — the drop-down follows whatever the code says.

The code editor with forest chosen in the Theme drop-down and the config block with theme: forest at the top of the code
Theme forest chosen: the block appears at the top of the code. Colours set with classDef, as in the default diagram, win over the theme.

5.6 Charts from a SharePoint list

The 📊 From a list tab draws a chart from the items of a list on the same site: an org chart from a staff list, a gantt chart from a task list, a bar chart of sales per person. You pick the list and the columns; the web part writes the Mermaid code for you.

  1. Open the code editor (3.4) and click the From a list tab.
  2. Click a chart type: Org chart, Gantt chart, Pie chart, Bar, Line, Treemap or Kanban. Hover over a type to see what it needs.
  3. Choose the list. Each list shows its number of items, e.g. Sales (4000).
  4. Check the columns. There is one drop-down per column the chart needs; the web part has already picked the most likely one.
  5. Type a Chart title if you want one, and decide on Keep in sync (below).
  6. Click OK. The chart is saved and drawn on the page.
The From a list tab: chart type tiles, the list MMLC Org (5), Name column Title and Reports to column Parent, Chart title, Keep in sync, and an org chart preview from CEO down to Developer
An org chart from a five-item staff list: Title is the name, Parent says who each person reports to.

What each chart type needs

Chart typeColumns you pickShows
Org chartName column, Reports to (a lookup to the same list, or text)Who reports to whom
Gantt chartTask, Start date column, End date column, Group by column (optional)Tasks on a time axis; items without a start date are left out
Pie chartGroup by, ValueThe share of each value of a column
BarGroup by, ValueOne bar per value of a column
LineGroup by, ValueA line over the values of a column, usually dates by month, quarter or year
TreemapGroup by, Then by (optional), ValueBoxes sized by count or sum, in one or two levels
KanbanBoard column (e.g. Status), Card textOne column per value, one card per item

Value is what each slice, bar or box measures: the number of items, or the sum or average of a number column (e.g. Σ Sum · Amount). When you group by a date column, you can also choose to group the dates by month, quarter or year.

Keep in sync

🔄 On

The chart is made from the list again each time the page opens, so it always shows the current items. Changes to the code are replaced.

Off

The chart is made once. After that it is ordinary Mermaid code that you can change on the My own code tab.

The tab that is open when you click OK decides what is saved. To change a list chart by hand, switch to My own code: the chart's code is already there. A web part that is linked to a list opens on the From a list tab.

Examples

Each picture below is the preview of one chart type, made from a test list on a SharePoint Online site.

Gantt chart Project plan from a task list, with three phases
Gantt chart: tasks with start and due dates, grouped by phase.
Pie chart from a list
Pie chart: sales per item, Amount summed.
Bar chart Amount per salesperson from a 4000-item sales list
Bar: the sum of Amount per salesperson, 4000 items.
Line chart from a list, values over time
Line: Amount summed per quarter of the sale date.
Treemap from a list
Treemap: sales by district, then by salesperson.
Kanban board from a task list
Kanban: one column per status, one card per task.
When the list changes: if the list is deleted, emptied or cannot be read, the web part shows a short notice above the chart it made last — for example The list for this chart was not found or The list has no items to chart. Large lists are read in full, past 5000 items.

Chapter 6Example library

The web part ships with 47 ready-made diagrams. Loading an example replaces the current code, re-renders the preview and saves the diagram at once, giving you a working starting point that you can customise.

6.1 Opening the examples section

  1. Open the code editor (see Chapter 3, section 3.4).
  2. On the My own code tab, click Example Data at the left of the toolbar. The panel opens over the code.
  3. The panel shows the 15 featured examples first, then the others under a heading per diagram type. Click any pill to load that example; it is saved at once.
The code editor with the Example Data panel open on the left, showing example buttons such as Clickable Server Architecture
The Example Data panel, open over the code. Each button loads one example; × closes the panel.
Tip: Load an example that matches the type of diagram you need, then edit the code to use your own data. This is faster than writing from scratch.
Flowchart Start OK? Wait Done Sequence A B Request Response Process Gantt Design Build Test Deploy Jan Feb Mar ER Diagram Order id date Product id name Mindmap Root Dev UX Ops QA Charts pie · sankey · xy · quadrant

6.2 Featured examples

The featured set contains 15 real-world demonstrations covering the most commonly used diagram types:

ExampleTypeDemonstrates
Clickable Server ArchitectureFlowchartColoured nodes, styled links, clickable nodes
Software Development WorkflowFlowchartSubgraphs, decision shapes, emoji labels
Microservices Payment FlowSequenceActors, alt/else, par blocks, autonumber
Enterprise System ContextC4C4Context, enterprise boundaries, relationships
AWS Three-Tier ArchitectureArchitectureGroups, service icons, directional connectors
CI/CD Deployment PipelineFlowchartMultiple subgraphs, conditional routing
Sprint Kanban BoardKanbanSwimlane columns, card items
Sales Revenue AnalyticsXY ChartBar + line series, axis labels
Campaign Performance MatrixQuadrantFour-quadrant scatter with labeled axes
Project Timeline with MilestonesGanttSections, task states, milestone markers
Energy Flow DistributionSankeyFlow values between sources and sinks
Product Strategy MindmapMindmapNested branches, Font Awesome icons
Git Feature Branch WorkflowGit GraphBranches, merges, release tags
E-Commerce Database SchemaER DiagramEntities, attributes, cardinality notations
Application State MachineStateStates, transitions, notes

6.3 Additional examples by type

Below the featured set, the panel lists 32 more examples under a heading per diagram type. They show more specialised patterns:

CategoryExamples
FlowchartShape library, user authentication flow, incident response, data pipeline, accessibility features
SequenceOAuth 2.0 flow, cache-aside pattern, Saga distributed transaction, linked actors
Class diagramObserver pattern, e-commerce domain model, repository pattern with generics
GanttAgile sprint planning, construction project schedule
Git GraphGitflow workflow
MindmapTechnology stack selection
CategoryExamples
ER DiagramLibrary management system
StateOrder lifecycle
JourneyCustomer purchase journey
TimelineCompany milestones
ArchitectureMicroservices architecture
Pie, Treemap, Requirement, SankeyBudget allocation, storage usage, requirements traceability, budget flow
ConfigCustom theme, hand-drawn style, ELK layout, math formulas

6.4 Solution showcase

Three examples whose names start with 🎯 E-Commerce (under the C4, Sequence and ER headings) demonstrate how the same system can be documented from multiple perspectives using different diagram types:

This set illustrates how a single business domain can be communicated through complementary views.

Chapter 7Diagram type reference

Each Mermaid diagram type is declared by a keyword on the first line of the code block. This chapter describes all supported types, their starting keyword, a minimal code example, and their primary use case.

20 diagram types — grouped by purpose Flow & Process Flowchart Sequence State User Journey Data & Relationships ER Diagram Class Diagram Requirement Architecture Architecture-beta C4 Project Planning Gantt Timeline Git Graph Kanban-beta Mindmap Data Visualisation Pie Chart XY Chart-beta Quadrant Sankey-beta Treemap-beta Block-beta

7.1 Flow and process diagrams

Flowchart

Keywords: graph TD  /  graph LR  /  flowchart TD

The most versatile diagram type. Nodes connected by arrows represent decisions, steps, and data flows. Direction is set after the keyword: TD (top-down), LR (left-right), TB (top-bottom), BT (bottom-top), RL (right-left). Supports subgraphs, custom node shapes, class-based styling, link styles, and clickable nodes.

graph TD
    A[Start] --> B{Ready?}
    B -->|Yes| C[Continue]
    B -->|No| D[Wait]
The sample above as Mermaid draws it

Sequence diagram

Keyword: sequenceDiagram

Shows the chronological order of messages between participants (people, services, systems). Supports actors, alternative blocks (alt/else), parallel execution (par), loops, and notes. Participants can have clickable links via the link directive.

sequenceDiagram
    Client->>Server: GET /data
    Server-->>Client: 200 OK
The sample above as Mermaid draws it

State diagram

Keyword: stateDiagram-v2

Models the states an object or system can be in and the transitions between them. Useful for documenting order lifecycles, UI screen flows, or any process with distinct states.

stateDiagram-v2
    [*] --> Pending
    Pending --> Shipped : confirm
    Shipped --> [*]
The sample above as Mermaid draws it

User journey

Keyword: journey

Plots a user experience across sections and steps, with a satisfaction score (1–5) and the actors involved at each step. Good for UX analysis and customer journey mapping.

journey
    title Checkout flow
    section Browse
        Search: 5: Customer
        Add to cart: 4: Customer
The sample above as Mermaid draws it

7.2 Data and relationship diagrams

Entity Relationship diagram

Keyword: erDiagram

Describes database tables (entities), their attributes, and the relationships and cardinalities between them. Uses standard ER notation: ||--o{ (one-to-many), }|..|{ (many-to-many), etc.

erDiagram
    ORDER ||--o{ ITEM : contains
    ORDER { int id string status }
The sample above as Mermaid draws it

Class diagram

Keyword: classDiagram

Documents object-oriented class structures, interfaces, inheritance hierarchies, and associations. Supports method signatures, access modifiers (+/-/#), and generics notation.

classDiagram
    Animal <|-- Dog
    Animal : +String name
    Animal : +speak()
The sample above as Mermaid draws it

Requirement diagram

Keyword: requirementDiagram

Traces system requirements to implementing components. Each requirement has an ID, description, risk level, and verification method. Components are linked to requirements they satisfy.

requirementDiagram
    requirement REQ_01 {
        id: 1
        text: "System must log all actions"
        risk: medium
    }
The sample above as Mermaid draws it

7.3 Architecture diagrams

Architecture diagram beta

Keyword: architecture-beta

Renders infrastructure and service architecture using named icons (server, database, internet, cloud). Services are grouped into subnets or regions and connected with directional connectors.

architecture-beta
    group cloud(cloud)[Cloud]
        service db(database)[Database] in cloud
        service api(server)[API] in cloud
    api:R --> L:db
The sample above as Mermaid draws it

C4 diagram

Keyword: C4Context / C4Container / C4Component

Implements the C4 model for software architecture documentation. C4Context shows system context (people, systems, boundaries). Relationships include communication descriptions.

C4Context
    Person(user, "User")
    System(app, "Web App")
    Rel(user, app, "Uses", "HTTPS")
The sample above as Mermaid draws it

7.4 Project planning diagrams

Gantt chart

Keyword: gantt

Horizontal bar chart for project schedules. Tasks are arranged in sections with start dates (absolute or relative), durations, and statuses (done, active). Milestone markers have zero duration.

gantt
    dateFormat YYYY-MM-DD
    section Design
    Wireframes : done, 2025-01-01, 7d
    Review : active, 2025-01-08, 3d
The sample above as Mermaid draws it

Timeline

Keyword: timeline

Displays events on a horizontal or vertical axis grouped by time period. Each period lists one or more events. Simpler than Gantt but useful for historical overviews and roadmaps.

timeline
    title Company history
    2018 : Founded
    2021 : Series A : 10 employees
    2025 : IPO
The sample above as Mermaid draws it

Git graph

Keyword: gitGraph

Visualises Git branch and commit history. Shows branches, commits with IDs, merges, and tags. Useful for documenting branching strategies such as Gitflow.

gitGraph
    commit id: "init"
    branch feature
    commit id: "add login"
    checkout main
    merge feature tag: "v1.0"
The sample above as Mermaid draws it

Kanban board

Keyword: kanban

Renders a Kanban board with named swimlane columns (To Do, In Progress, Review, Done) and card items within each column.

kanban
    column1[To Do]
        task1[Write tests]
    column2[In Progress]
        task2[Build API]
The sample above as Mermaid draws it

7.5 Data visualisation

Pie chart

Keyword: pie

Simple proportional chart. Each slice is defined by a label and a numeric value. A title can be provided after the keyword.

pie title Browser share
    "Chrome" : 65
    "Edge" : 18
    "Firefox" : 10
The sample above as Mermaid draws it

XY chart beta

Keyword: xychart-beta

Renders bar and line series on a common X/Y axis. Axes are explicitly defined with labels and value ranges. Multiple series types can appear on one chart.

xychart-beta
    title "Monthly Revenue"
    x-axis [Jan, Feb, Mar, Apr]
    y-axis "USD (k)" 0 --> 100
    bar [42, 58, 73, 91]
The sample above as Mermaid draws it

Quadrant chart

Keyword: quadrantChart

Four-quadrant scatter plot where each quadrant is named. Items are placed by X and Y coordinates (0.0–1.0). Good for priority matrices and BCG-style analysis.

quadrantChart
    x-axis Low Impact --> High Impact
    y-axis Low Effort --> High Effort
    Feature A: [0.8, 0.3]
The sample above as Mermaid draws it

Sankey diagram beta

Keyword: sankey-beta

Flow diagram where the width of each arrow is proportional to the flow value. Each line defines: Source, Target, Value. Useful for energy flows, budget allocations, and material flows.

sankey-beta
    Solar,Electricity,80
    Wind,Electricity,40
    Electricity,Homes,70
The sample above as Mermaid draws it

Treemap beta

Keyword: treemap-beta

Hierarchical proportional chart where nested rectangles represent values at each level of a tree. Good for storage breakdowns, organisational sizes, or market share.

treemap-beta
    "Documents"
        "PDFs": 40
        "Images": 25
The sample above as Mermaid draws it

7.6 Other types

Block diagram beta (block-beta): boxes in columns you set yourself.

Mindmap

Keyword: mindmap

Radial branching structure rooted at a central concept. Child nodes are indented relative to their parent. Supports Font Awesome icon annotations (::icon(fa fa-...)).

mindmap
    root((Strategy))
        Growth
            Marketing
        Operations
The sample above as Mermaid draws it

Diagram configuration (YAML front matter)

Syntax: --- block before the diagram keyword

Any Mermaid diagram can include a YAML front-matter block to override the rendering theme, look, and individual theme variables. Common options:

---
config:
  theme: dark
  look: handDrawn
---
graph LR
    A --> B
The sample above as Mermaid draws it

Chapter 8Troubleshooting

This chapter covers the most common issues encountered when using the Mermaid Web Part, the permissions required for each action, known limitations, and behaviour on mobile devices.

8.1 Common issues and solutions

SymptomLikely causeSolution
Preview shows a red error box Syntax error in the Mermaid code. Read the error message — it usually names the line or token that failed. Check spelling of the diagram keyword, unclosed brackets, or an invalid arrow style. In the editor the preview keeps the last diagram that worked, and OK is blocked until the code is valid.
Diagram disappeared after saving The diagram file could not be written to Site Assets, or it was deleted. Check that you can add and edit files in the site's Site Assets library, then edit the diagram again and click OK. An administrator can look for the Mermaid_<instance ID>.txt file there (see 3.3).
Edit button / editor does not open The page is not in edit mode. Click Edit on the page first (top right on a modern page, the ribbon on a classic page). Then select the web part and click its Edit properties (sliders) button, or the gear icon on a classic page (see 3.4).
Click handlers do not navigate The page is still in edit mode, or the address in the click line is mistyped. Links work in view mode: publish or leave edit mode, then click again. Check the address: a full address (https://...) and an address relative to the page (../SitePages, as in the default diagram) both work. Add _blank at the end of the line to open a new tab.
Node ID list in Add Click is empty The editor could not parse node IDs from the current code. The parser only recognises standard Mermaid node declarations (A[label], A(label), etc.). Ensure the code is valid and that at least one node is declared before opening the dialog.

8.1 Common issues and solutions (continued)

SymptomLikely causeSolution
Mermaid is not in the toolbox The app is not installed in the App Catalog, or not added to this site. Ask the SharePoint administrator to upload the package and, if needed, add the app under Site contents >New >App (see 2.3).
A registration dialog covers the diagram The Standard edition is in its trial period, or the trial has ended. Enter your e-mail address and registration key (see 2.6), or install the Premium edition.
Edit in Live opens a blank page Browser popup blocker prevented the new tab from opening. Allow popups from the SharePoint site, or right-click the Edit in Live button and choose Open link in new tab manually.

8.1 Common issues and solutions (continued)

SymptomLikely causeSolution
Old diagram still shows after redeployment Browser cache is serving the previous JavaScript bundle. Perform a hard refresh: Ctrl+Shift+R (Chrome/Edge) or Ctrl+F5 (Firefox). If it persists for everyone: in SharePoint Online, check in the App Catalog that the new version is deployed; on-premises, an administrator can also clear the blob cache.
A list chart shows a notice above it The list the chart is made from was deleted, renamed, emptied, or the reader has no access to it. The web part keeps the chart it made last. Restore the list or its items, or open the editor and pick another list on the From a list tab (5.6). To keep the chart without the list, turn off Keep in sync.
Scrollbars around the diagram The diagram is wider or taller than the web part. It is drawn at full size so its text stays readable. Scroll to see the rest. To avoid scrolling, use a wider page section (a one-column section), reduce the diagram, or for a wide diagram switch to top-down layout: replace LR with TD in the diagram keyword.

8.1 Common issues and solutions (continued)

SymptomLikely causeSolution
Right-click context menu does not appear Right-click was on the background, not on a diagram node. Right-click directly on a coloured node shape. The context menu only appears on Mermaid nodes, not on the empty area around the diagram.
OK button does not close the editor The preview is showing a Mermaid syntax error. The editor refuses to save a diagram that cannot be rendered — the red preview explains what is wrong. Fix the code until the preview renders, then click OK. To remove the diagram entirely, clear the code editor (an empty editor saves normally).
Notice: the Site Assets library is blocked by a folder named "siteassets" (classic pages) A classic package older than 0.1.6.3 made a plain folder instead of the Site Assets library. Install 0.1.6.5 or later. A site owner opens the page once: the files are kept, the folder is recycled, Site Assets is created and the diagram draws. Members and visitors only see the notice until then.

8.2 Permissions

SharePoint's own page permissions decide who can do what; the web part adds none of its own (table in 3.5):

🔒 Administrator ✓ Install the app / package ✓ Add it to sites ✓ All editor permissions Online: SharePoint admin · on-prem: App Catalog / site coll. admin ✏ Page Editor ✓ Add web part to a page ✓ Open code editor ✓ Save and publish diagrams Requires: Contribute / Design 👁 Visitor ✓ View rendered diagram ✓ Click interactive nodes ✗ Cannot open editor Requires: Read

8.3 Known limitations

The following limitations apply to all versions of the Mermaid Web Part:

LimitationDetail
No layout control Mermaid positions all nodes algorithmically. You cannot drag nodes to custom positions. For diagrams requiring exact placement, use Visio or PowerPoint instead.
Data only from lists on the same site Hand-written diagrams do not change by themselves. Charts made on the From a list tab (5.6) update from a list on the same site; data from other sites, Excel files or databases is not read.
No embedded images Mermaid does not support embedding raster images inside diagram nodes. Only text labels, Font Awesome icons, and shapes are available.
Large diagrams can be slow Diagrams with 50+ nodes may take a noticeable time to render. If the preview is slow, reduce the number of nodes or split the diagram into smaller pieces.
Beta diagram types may change Types marked -beta (xychart-beta, sankey-beta, treemap-beta, architecture-beta, block-beta) may have their syntax changed or removed in future Mermaid engine updates.

8.4 Mobile and tablet use

Visitors can view diagrams and tap their links on any phone or tablet. Editing needs a desktop browser: on a small screen the editor dialog can be hidden behind the on-screen keyboard. See 3.6 for details.

Quick Reference

A two-page summary of keyboard shortcuts, toolbar actions, snippet categories, common diagram starters, and click handler syntax.

Keyboard shortcuts (in editor)

KeyAction
TabInsert 2 spaces
Ctrl+ZUndo
Ctrl+YRedo
Ctrl+ASelect all
Ctrl+CCopy
Ctrl+VPaste

Toolbar buttons

ButtonAction
📊 From a list (tab)Chart from a SharePoint list (5.6)
ThemeWrite the chosen theme into the code
✏ Edit in LiveOpen diagram in mermaid.live
📋 SnippetsInsert code at cursor
🔗 Add ClickGenerate click handler
OKSave and re-render
Cancel / ×Discard changes

Right-click context menu

ActionEffect
🔗 Add LinkOpens Add Click dialog with node pre-selected
📝 Select CodeSelects node definition in editor

Snippet categories

CategoryContents
Quick StartFlowchart, Sequence, Gantt, Class, State starters
Node ShapesRect, Rounded, Circle, Diamond, Hex, DB…
Link StylesSolid, Dashed, Thick, Labeled, Bidir, No Arrow
StylingclassDef, linkStyle, style, subgraph
Interactiveclick, callback, actor link, accTitle/accDescr
ThemesCustom colors, Hand-Drawn, Dark, Forest YAML

Click handler syntax

click <NodeID> "<URL>" "<Tooltip>" _blank

Example:
click A "https://intranet.example.com" "Go" _blank

Same tab: omit _blank

Theme front matter

---
config:
  theme: dark
---
graph TD
    A --> B

Themes: base • default • dark • forest • neutral
Add look: handDrawn for sketch style.

Common diagram starters

TypeFirst line
Flowchart (↓)graph TD
Flowchart (→)graph LR
SequencesequenceDiagram
ClassclassDiagram
StatestateDiagram-v2
ER diagramerDiagram
Ganttgantt
Git graphgitGraph
Mindmapmindmap
Timelinetimeline
Journeyjourney
Pie chartpie title My Chart
Kanbankanban
QuadrantquadrantChart
C4 ContextC4Context
Architecturearchitecture-beta
XY Chartxychart-beta
Sankeysankey-beta
Treemaptreemap-beta
RequirementsrequirementDiagram
Remember: Clicking OK saves the diagram at once; all visitors see it on their next page load.

Glossary

Definitions of Mermaid, SharePoint, and web part terms used throughout this guide. Terms are grouped by topic; within each group they are alphabetical.

Mermaid syntax

TermDefinition
classDef A Mermaid statement that defines a named CSS-like style (fill, stroke, colour) that can then be applied to nodes with class or by attaching the class in the node's shape declaration.
click handler A Mermaid click statement that turns a node into a hyperlink. Syntax: click NodeID "URL" "Tooltip" _blank. Omit _blank to open in the same tab.
diagram type The first keyword of a Mermaid diagram that tells the renderer which grammar to use (graph, sequenceDiagram, classDiagram, etc.). See Chapter 7 for the full list.
edge / link A connection between two nodes. Solid arrow -->, dashed -.->, thick ==>, no arrow ---. Labels: -->|label|.
front matter An optional YAML block at the top of a diagram (delimited by ---) that sets configuration such as theme, look: handDrawn, or per-diagram overrides. Travels with the code when saved.
linkStyle A Mermaid statement that styles a specific edge by its index (0-based) — colour, stroke width, dash pattern.

Mermaid syntax (continued)

TermDefinition
node A shape in a diagram (rectangle, rounded, circle, diamond, hexagon, cylinder, etc.). Every node has an ID (used in code and click handlers) and a label (displayed text).
node ID The short alphanumeric identifier used to reference a node in edges, click handlers, and styling (e.g. A, Home, node1).
subgraph A named grouping of nodes inside a flowchart, rendered as a bordered container with a title. Syntax: subgraph Title … end.
theme One of Mermaid's built-in colour schemes: default, base, dark, forest, neutral. Set via the front matter or the dialog's theme picker.

Editor and web part

TermDefinition
Add Click dialog The dialog that generates a click statement — pick a node ID, enter a URL, tooltip, and target. Reached from the toolbar or the right-click Add Link action.
Code editor The dialog that opens when you edit the web part. Left pane: Mermaid source. Right pane: live preview. Toolbar: Edit in Live, Snippets, Add Click, Themes.
Edit in Live Toolbar button that opens the current diagram in mermaid.live for full-screen editing and configuration.
Live preview The right pane of the code editor that re-renders the diagram as you type. If the code is invalid, an error strip appears and OK is blocked.
Snippets menu A drop-down menu of ready-to-insert Mermaid fragments organised by category (Quick Start, Node Shapes, Link Styles, Styling, Interactive, Themes).
Web Part A SharePoint component that can be added to a page. Each Mermaid Web Part instance stores its own diagram code in its own text file in the Site Assets library.

SharePoint

TermDefinition
App Catalog The tenant-scoped site collection where modern SPFx solution packages (.sppkg) are uploaded and deployed. The SPFx editions of the Mermaid Web Part (SharePoint Online and on-premises) are installed from here; the classic edition uses the solution gallery.
Classic page The pre-modern SharePoint page layout that supports the classic web part gallery and web part zones. The classic edition of the Mermaid Web Part (.wsp) runs on these pages.
Contribute / Design / Full Control SharePoint permission levels. Contribute or higher is required to add and edit web parts. Read is sufficient to view rendered diagrams.
Site Assets The site library where the Mermaid Web Part keeps each diagram, one file Mermaid_<instance ID>.txt per web part. No list or database is used.
Web Part gallery The classic SharePoint dialog (Insert >Web Part) that lists installed web parts by category. Not used by the Mermaid web part: on classic pages it is added by putting <div id="MMMain"></div> into the page source, on modern pages from the toolbox (see 3.1).
Web Part zone A region on a classic SharePoint page where web parts can be added. Each zone can host multiple web parts; on classic pages the Mermaid web part shows one diagram per page.

Rendering

TermDefinition
Hand-drawn look A sketch-style rendering enabled by adding look: handDrawn to the diagram's front matter. Node outlines and edges become slightly wobbly for a whiteboard effect.
Scoped render The web part renders Mermaid only within its own DOM element, so multiple Mermaid Web Parts on the same page do not re-render each other.
SVG Scalable Vector Graphics — the format Mermaid produces for the rendered diagram. Scales cleanly at any zoom and prints crisply.

Index

Alphabetical index of features, syntax, and concepts. References point to the chapter and section where each topic is introduced: 3.5 means Chapter 3, Section 5; "Quick Ref" points to the single-page reference card and "Glossary" to the terms appendix.

A

Adding web part to a page — 3.1
Add Click dialog — 5.3
Administrator role — 3.5, 8.2
App Catalog — 2.1, 2.3, Glossary
Architecture diagram — 7.3, Quick Ref

C

C4 Context diagram — 7.3, Quick Ref
Class diagram — 7.2, Quick Ref
classDef statement — 3.2, Glossary
Click handlers — 5.3, Quick Ref
Code editor overview — 4.1
Colours — 6.2, snippet Themes
Context menu (right-click) — 5.4, Quick Ref
Contribute permission — 3.5, 8.2

D

Dark theme — 5.5, Quick Ref
Dashed arrows — snippet Link Styles
Default diagram — 3.2
Diagram taxonomy chart — 6 (intro)
Diagram types (full list) — 6, Quick Ref

E

Edit in Live (mermaid.live) — 5.1, Quick Ref
Editing an existing diagram — 3.4, 4.1
Editor toolbar — 4.5, Quick Ref
ER diagram — 7.2, Quick Ref
Error messages — 4.3, 8.1
Examples gallery — 5

F

Flowchart — 7.1, Quick Ref
Forest theme — 5.5, Quick Ref
Front matter (YAML) — 5.5, Glossary

G

Gantt chart — 7.4, Quick Ref; from a list 5.6
Git graph — 7.4, Quick Ref
graph LR / graph TD — 7.1, Quick Ref

H

Hand-drawn look — 5.5, Glossary

I

Installer (Install-MermaidWebPart.ps1) — 2.2
Installing the web part — 2.1–2.4
Interactive nodes — see Click handlers

K

Kanban board — 7.4, Quick Ref; from a list 5.6
Keep in sync (list charts) — 5.6
Keyboard shortcuts — 4.4, Quick Ref

L

Limitations, known — 8.3
List charts (From a list) — 5.6, 8.1
Link (click handler) — see Click handlers
linkStyle statement — 3.2, Glossary
Live preview — 4.3, Glossary

Index (continued)

M

mermaid.live — see Edit in Live
Mindmap — 7.6, Quick Ref
Mobile and tablet use — 3.6, 8.4

N

Node ID / label — Glossary
Node shapes — snippet Node Shapes, Quick Ref

O

Org chart from a list — 5.6

P

Page permissions — 3.5, 8.2
Pie chart — 7.5; from a list 5.6
Premium edition — 2.1, 2.6

Q

Quadrant chart — 7.5, Quick Ref
Quick Reference card — Quick Ref page

R

Read permission (visitor) — 3.5, 8.2
Registration key — 2.6, 8.1
Removing the web part — 2.3
Rendering — 4.3, Glossary
Requirement diagram — 7.2, Quick Ref
Right-click context menu — 5.4, Quick Ref

S

Sankey diagram — 7.5, Quick Ref
Saving diagrams — 3.3, 4.5, 8.1
Scrollbars (large diagrams) — 3.6, 8.1
Sequence diagram — 7.1, Quick Ref
Site Assets library — 3.3, Glossary
Snippets menu — 5.2, Quick Ref
SPFx editions — 2.1
State diagram — 7.1, Quick Ref
Styling snippets — 5.2
Subgraph — Glossary

T

Themes — 5.5, Quick Ref
Timeline — 7.4, Quick Ref
Toolbar — see Editor toolbar
Treemap — 7.5, Quick Ref
Trial (30 days) — 2.6
Troubleshooting — 8.1

U

Upgrading the web part — 2.3
User journey — 7.1, Quick Ref

V

Version (web part) — Cover
Visitor role — 3.5, 8.2

X

XY chart — 7.5, Quick Ref

Y

YAML front matter — see Front matter