The Mermaid Web Part brings professional, text-based diagramming to SharePoint pages, modern and classic, in SharePoint Online and on-premises.
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.
Start from one of 47 ready-made examples and change the words. The preview shows the result as you type.
Any box can link to a site, a document or a list, so a diagram becomes the way into your intranet.
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.
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.
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.
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.
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.
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.
Mermaid runs in any browser, free of charge. Viewers do not need Visio, Lucidchart, or any other installed tool to see a rendered diagram.
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.
Mermaid renders SVG, which is natively accessible. Accessibility titles and descriptions can be added directly in the code with accTitle and accDescr directives.
Mermaid is excellent for structured, logic-driven diagrams. It is a less natural fit when:
Because Mermaid is open-source and widely adopted, a large ecosystem has grown around it:
| Resource | Description |
|---|---|
Mermaid Live Editormermaid.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. |
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:
click syntax is not obvious to non-developers. The Add Click Handler tool generates correct click syntax from a form, making interactive diagrams accessible to all authors.Side-by-side editor and live preview. Changes are reflected within 500 ms of typing.
15 featured examples plus 32 more, grouped by type. One click loads an example into the editor.
Insert shapes, link styles, themes, and click handlers at the cursor from a categorised menu.
A guided form generates Mermaid click syntax for any diagram node with no manual coding.
Open any diagram in the official Live Editor for advanced editing, then paste code back.
Right-click any preview node to add a link or jump to its definition in the code editor.
Org chart, gantt, pie, bar, line, treemap or kanban from the items of a list on the site, kept in sync if you want.
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:
| Type | Keyword |
|---|---|
| Flowchart | graph TD / flowchart |
| Sequence diagram | sequenceDiagram |
| Class diagram | classDiagram |
| State diagram | stateDiagram-v2 |
| Entity Relationship | erDiagram |
| Gantt chart | gantt |
| Git graph | gitGraph |
| Mindmap | mindmap |
| Timeline | timeline |
| User journey | journey |
| Type | Keyword |
|---|---|
| Architecture diagram | architecture-beta |
| C4 diagram | C4Context |
| Pie chart | pie |
| Sankey diagram | sankey-beta |
| XY chart | xychart-beta |
| Quadrant chart | quadrantChart |
| Kanban board | kanban |
| Treemap | treemap-beta |
| Requirement diagram | requirementDiagram |
| Block diagram | block-beta |
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.
| SharePoint | Package | How the administrator installs it |
|---|---|---|
| SharePoint Online (modern pages) | MM_SPFX_OnLine_<version>.sppkg | Upload 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>.sppkg | Upload to the on-premises App Catalog, then add the web part to a modern page. |
| SharePoint 2013 – SE, classic pages | MM_Sand_<version>.wsp | Upload 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 above | Install-MermaidWebPart.ps1 | A PowerShell installer that installs any of the three packages above, modern or classic, for you (2.2). |
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.
Install-MermaidWebPart.ps1 and open it in PowerShell, or press F5 in the PowerShell ISE. The installer window opens..sppkg packages, or the site for the .wsp. SharePoint Online also needs the app id of your own Entra app registration for PnP PowerShell.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.
Install once and every editor can use it. These steps are for the SPFx packages; the Installer can do them for you (2.2).
.sppkg file and click OK.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.
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.
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.
.wsp file and click OK..wsp chosen in Add a solution.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.
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).
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.
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.
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).
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.
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.
If you have any kind of problem or question about the Mermaid Web Part, there are several ways of contacting us:
| Channel | Address | For |
|---|---|---|
| support@kalmstrom.com | Technical issues | |
| sales@kalmstrom.com | Subscription and general issues | |
| finance@kalmstrom.com | Invoices, payments, quotations | |
| Telephone | +46 739 206 106 | |
| Teams | peter@kalmstrom.com | Chats, remote sessions |
| Zoom | peter@kalmstrom.com | Chats, remote sessions |
This chapter explains how to add the Mermaid Web Part to a SharePoint page and what you see when it first loads.
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.
<div id="MMMain"></div> at that place and click OK.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:
classDef declarationslinkStyleclick syntax) that open parts of your own site: the site home, site pages, site settings, documents and site contentsYou can replace this diagram at any time by opening the code editor (see Chapter 4).
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.
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.
To change a diagram that is already on the page:
Access to the Mermaid Web Part is controlled entirely by SharePoint's standard page permissions. No special web part-level permissions exist.
| Role | Required permission | Can 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. |
The web part behaves differently in view mode compared to edit mode on small screens:
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.
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.
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.
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.
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.
B -->): the preview turns red and names line 3. Fix the code and the diagram comes back.| Key | Action |
|---|---|
| Tab | Insert two spaces at the cursor (does not change keyboard focus) |
| Ctrl+Z | Undo (browser native) |
| Ctrl+Y | Redo (browser native) |
| Ctrl+A | Select all code (browser native) |
| Ctrl+C / V | Copy / Paste (browser native) |
The toolbar at the bottom of the editor contains two controls:
A grey information row at the bottom of the editor shows:
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).
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.
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:
| Category | Contents |
|---|---|
| Quick Start | Complete starter templates for Flowchart, Sequence, Gantt, Class, and State diagrams |
| Node Shapes | Individual shape declarations: Rectangle, Rounded, Circle, Diamond, Hexagon, Database, Subprocess, Trapezoid |
| Link Styles | Arrow variants: Solid, Dashed, Thick, Labeled, Bidirectional, No Arrow |
| Styling | Class definitions, link style rules, inline node styles, subgraph wrapper |
| Interactive | Click handler, callback function, sequence actor link, accessibility labels |
| Themes | YAML front-matter blocks for Custom Colors, Hand-Drawn, Dark, and Forest themes |
The 🔗 Add Click button opens a dialog that generates the Mermaid click syntax for making a diagram node into a hyperlink.
| Field | Description |
|---|---|
| Node ID | Drop-down list of all node IDs detected in the current diagram. Select the node you want to make clickable. |
| Target URL | The destination URL. Click 📌 Use Current Site URL to prefill with the current SharePoint site URL. |
| Tooltip | Text shown when the user hovers over the node. Defaults to "Click to open" if left empty. |
| Open in New Tab | When 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
Right-clicking a node in the live preview panel opens a small context menu with two actions:
| Action | What 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. |
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.
classDef, as in the default diagram, win over the theme.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.
| Chart type | Columns you pick | Shows |
|---|---|---|
| Org chart | Name column, Reports to (a lookup to the same list, or text) | Who reports to whom |
| Gantt chart | Task, Start date column, End date column, Group by column (optional) | Tasks on a time axis; items without a start date are left out |
| Pie chart | Group by, Value | The share of each value of a column |
| Bar | Group by, Value | One bar per value of a column |
| Line | Group by, Value | A line over the values of a column, usually dates by month, quarter or year |
| Treemap | Group by, Then by (optional), Value | Boxes sized by count or sum, in one or two levels |
| Kanban | Board column (e.g. Status), Card text | One 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.
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.
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.
Each picture below is the preview of one chart type, made from a test list on a SharePoint Online site.
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.
The featured set contains 15 real-world demonstrations covering the most commonly used diagram types:
| Example | Type | Demonstrates |
|---|---|---|
| Clickable Server Architecture | Flowchart | Coloured nodes, styled links, clickable nodes |
| Software Development Workflow | Flowchart | Subgraphs, decision shapes, emoji labels |
| Microservices Payment Flow | Sequence | Actors, alt/else, par blocks, autonumber |
| Enterprise System Context | C4 | C4Context, enterprise boundaries, relationships |
| AWS Three-Tier Architecture | Architecture | Groups, service icons, directional connectors |
| CI/CD Deployment Pipeline | Flowchart | Multiple subgraphs, conditional routing |
| Sprint Kanban Board | Kanban | Swimlane columns, card items |
| Sales Revenue Analytics | XY Chart | Bar + line series, axis labels |
| Campaign Performance Matrix | Quadrant | Four-quadrant scatter with labeled axes |
| Project Timeline with Milestones | Gantt | Sections, task states, milestone markers |
| Energy Flow Distribution | Sankey | Flow values between sources and sinks |
| Product Strategy Mindmap | Mindmap | Nested branches, Font Awesome icons |
| Git Feature Branch Workflow | Git Graph | Branches, merges, release tags |
| E-Commerce Database Schema | ER Diagram | Entities, attributes, cardinality notations |
| Application State Machine | State | States, transitions, notes |
Below the featured set, the panel lists 32 more examples under a heading per diagram type. They show more specialised patterns:
| Category | Examples |
|---|---|
| Flowchart | Shape library, user authentication flow, incident response, data pipeline, accessibility features |
| Sequence | OAuth 2.0 flow, cache-aside pattern, Saga distributed transaction, linked actors |
| Class diagram | Observer pattern, e-commerce domain model, repository pattern with generics |
| Gantt | Agile sprint planning, construction project schedule |
| Git Graph | Gitflow workflow |
| Mindmap | Technology stack selection |
| Category | Examples |
|---|---|
| ER Diagram | Library management system |
| State | Order lifecycle |
| Journey | Customer purchase journey |
| Timeline | Company milestones |
| Architecture | Microservices architecture |
| Pie, Treemap, Requirement, Sankey | Budget allocation, storage usage, requirements traceability, budget flow |
| Config | Custom theme, hand-drawn style, ELK layout, math formulas |
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.
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.
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]
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
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 --> [*]
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
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 }
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()
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 }
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
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")
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
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
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"
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]
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
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]
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]
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
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
Block diagram beta (block-beta): boxes in columns you set yourself.
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
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
theme: base | default | dark | forest | neutrallook: handDrawn — sketch-style renderinglayout: elk — alternative graph layout enginethemeVariables: — override individual coloursThis 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.
| Symptom | Likely cause | Solution |
|---|---|---|
| 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)
| Symptom | Likely cause | Solution |
|---|---|---|
| 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)
| Symptom | Likely cause | Solution |
|---|---|---|
| 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)
| Symptom | Likely cause | Solution |
|---|---|---|
| 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. |
SharePoint's own page permissions decide who can do what; the web part adds none of its own (table in 3.5):
The following limitations apply to all versions of the Mermaid Web Part:
| Limitation | Detail |
|---|---|
| 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. |
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.
A two-page summary of keyboard shortcuts, toolbar actions, snippet categories, common diagram starters, and click handler syntax.
| Key | Action |
|---|---|
| Tab | Insert 2 spaces |
| Ctrl+Z | Undo |
| Ctrl+Y | Redo |
| Ctrl+A | Select all |
| Ctrl+C | Copy |
| Ctrl+V | Paste |
| Button | Action |
|---|---|
| 📊 From a list (tab) | Chart from a SharePoint list (5.6) |
| Theme | Write the chosen theme into the code |
| ✏ Edit in Live | Open diagram in mermaid.live |
| 📋 Snippets | Insert code at cursor |
| 🔗 Add Click | Generate click handler |
| OK | Save and re-render |
| Cancel / × | Discard changes |
| Action | Effect |
|---|---|
| 🔗 Add Link | Opens Add Click dialog with node pre-selected |
| 📝 Select Code | Selects node definition in editor |
| Category | Contents |
|---|---|
| Quick Start | Flowchart, Sequence, Gantt, Class, State starters |
| Node Shapes | Rect, Rounded, Circle, Diamond, Hex, DB… |
| Link Styles | Solid, Dashed, Thick, Labeled, Bidir, No Arrow |
| Styling | classDef, linkStyle, style, subgraph |
| Interactive | click, callback, actor link, accTitle/accDescr |
| Themes | Custom colors, Hand-Drawn, Dark, Forest YAML |
click <NodeID> "<URL>" "<Tooltip>" _blankclick A "https://intranet.example.com" "Go" _blank_blank
---config: theme: dark---graph TD A --> B
Themes: base • default • dark • forest • neutral
Add look: handDrawn for sketch style.
| Type | First line |
|---|---|
| Flowchart (↓) | graph TD |
| Flowchart (→) | graph LR |
| Sequence | sequenceDiagram |
| Class | classDiagram |
| State | stateDiagram-v2 |
| ER diagram | erDiagram |
| Gantt | gantt |
| Git graph | gitGraph |
| Mindmap | mindmap |
| Timeline | timeline |
| Journey | journey |
| Pie chart | pie title My Chart |
| Kanban | kanban |
| Quadrant | quadrantChart |
| C4 Context | C4Context |
| Architecture | architecture-beta |
| XY Chart | xychart-beta |
| Sankey | sankey-beta |
| Treemap | treemap-beta |
| Requirements | requirementDiagram |
Definitions of Mermaid, SharePoint, and web part terms used throughout this guide. Terms are grouped by topic; within each group they are alphabetical.
| Term | Definition |
|---|---|
| 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)
| Term | Definition |
|---|---|
| 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. |
| Term | Definition |
|---|---|
| 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. |
| Term | Definition |
|---|---|
| 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. |
| Term | Definition |
|---|---|
| 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. |
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.