Mermaid diagrams

The Mermaid diagram brings native diagram creation directly into the editor. Powered by Mermaid.js, it lets you write text-based diagram syntax and see a rendered, visual diagram in real time - all without leaving your documentation workspace. Diagrams are stored as editable source code alongside a rendered image. This means your diagrams are always re-editable and never become stale static screenshots.

What is Mermaid.js?

Mermaid.js is an open-source diagramming library that converts plain text syntax into visual diagrams. Instead of drawing shapes manually in a separate tool, you describe the diagram in text and Mermaid renders it. Document360 embeds Mermaid.js directly in the editor, so the entire workflow happens without leaving your article.

Example: The following four lines of text produce a complete flowchart:

graph TD
  A[User submits ticket] --> B{Priority?}
  B -- High --> C[Notify on-call team]
  B -- Low  --> D[Add to backlog]

When to use Mermaid diagrams

Use Mermaid diagrams when your content involves a process, relationship, or structure that is harder to explain in words alone. Some common scenarios:

• A technical writer documenting an approval flow or onboarding journey
• A developer or architect illustrating an API interaction, system architecture, or database schema
• A product manager mapping a user journey or visualizing a project timeline
• A support team building a troubleshooting flowchart or escalation path

If you find yourself describing a sequence of steps or connections between components across multiple paragraphs, a diagram will almost always communicate it faster.

Key benefits

Inserting a Mermaid diagram

To insert a Mermaid diagram into your article:

1. Click inside the article body where you want the diagram to appear.
2. Type / (forward slash) to trigger the slash command menu.
3. Type Mermaid to filter the suggestions.
4. Select Mermaid diagram from the dropdown.

Picking a template

Once you trigger the Mermaid diagram insertion, the template selection modal appears. This is where you choose the starting point for your diagram.

• From a template — Browse or search the 23 available templates, then click one. The editor opens with that template's syntax pre-loaded.
• From blank — Click Blank to open the editor with an empty syntax panel. Use this only if you already know Mermaid syntax.

Choosing a template

1. Browse the 23 template cards or type a keyword (e.g. flow, sequence, gantt) in the search bar.
2. Click the template card that matches what you want to create.
3. The editor opens with that template's syntax pre-loaded. Edit it further to fit your content.

Using a blank canvas

1. Click the Blank option in the template grid.
2. The editor opens with an empty syntax panel.
3. Type your Mermaid syntax from scratch.

Writing and previewing your diagram

The Mermaid diagram editor is a two-panel workspace. The left panel is where you write your Mermaid syntax. The right panel shows you a live preview of the diagram as you type.

1. Start with a diagram type declaration on the first line. This tells Mermaid what kind of diagram to render.

   Diagram type	First line
   Flowchart (top to bottom)	graph TD
   Flowchart (left to right)	graph LR
   Sequence diagram	sequenceDiagram
   Class diagram	classDiagram
   Gantt chart	gantt
   State diagram	stateDiagram-v2
   Entity-relationship diagram	erDiagram
   Pie chart	pie
   Mindmap	mindmap

2. Add nodes, connections, and labels on the following lines. Each line you type immediately updates the preview on the right.

3. If you are working from a template, simply replace the placeholder text with your own labels and connections.

If your syntax has very long lines (e.g. long node labels or detailed edge descriptions), click the Wrap code toggle below the syntax panel to wrap long lines within the visible editor width. This does not affect the diagram output — it only changes how the code appears in the editor.

Preview controls

The right panel updates instantly as you type. Use the preview controls to inspect your diagram before inserting it.

Zoom in / Zoom out — Click the zoom in (+) or zoom out (−) buttons to increase or decrease the magnification of the preview. Use this to inspect specific parts of a complex diagram without affecting the actual diagram size in the article.

Fit to screen — Click the fit to screen ( ) icon to reset the zoom level so the entire diagram is visible in the preview area without scrolling. Use this for a final review before inserting.

Expand / Collapse — Click the expand ( ) icon in the preview panel toolbar to hide the syntax editor and expand the preview to fill the full modal width. Click the collapse ( ) icon to return to the split-panel view and continue editing.

Handling syntax errors

If your syntax is invalid, the preview shows an error and the Insert button is disabled.

1. Read the error message. It includes the line number causing the issue.
2. Fix that line in the syntax panel.
3. The preview updates automatically. Once valid, the Insert button becomes active.

Common errors and fixes

:::(Caution) (

Inserting the diagram into the article

Once the preview is correct and error-free, click Insert. Document360 converts the diagram to an SVG image and places it at your cursor position.

Two things are saved for every diagram:

• The rendered SVG image — visible in the article and on the KB site.
• The Mermaid syntax — stored privately, used when you edit the diagram later.

Managing an inserted diagram

Click on any inserted diagram to open the bubble menu.

Editing an existing diagram

Every Mermaid diagram you insert can be edited at any time, even after the article has been published. The original syntax is always stored.

1. Click the diagram, then click Edit diagram in the bubble menu.
2. The editor opens with the stored syntax and a live preview.
3. Make your changes.
4. Click Update. The diagram in the article is replaced; position and alignment are preserved.

If you click Cancel or (X) after making changes, a confirmation dialog appears. Click Yes, discard to exit without saving, or No, go back to continue editing.

How readers see your diagrams

On the knowledge base site, diagrams appear as static SVG images embedded in the article. Readers can click any diagram to open a full-screen overlay, which is useful for large or complex diagrams. Editing controls and source syntax are never exposed to readers.

Best practices

• One diagram, one idea. If a flowchart exceeds 15–20 nodes, split it into an overview diagram and a detail diagram.
• Always add a caption. Use the caption option in the bubble menu to label every diagram. It helps readers understand context at a glance.
• Use SVG for external use. SVG is infinitely scalable with no quality loss. Use PNG only when the destination tool doesn't support SVG.
• Copy to duplicate, not to rebuild. Use the Copy bubble menu action to duplicate a diagram. Each copy has independent syntax — editing one does not affect the other. Pasting a Mermaid diagram outside of Document360 (e.g. into another tool) will only paste the image, not the source syntax.

Available templates

The following templates are available in the Template Selection screen. Search by name or keyword to find the right one quickly.

FAQ