# Mermaid

## Overview

The Mermaid section widget enables laboratory professionals to create and embed interactive diagrams directly within Labii records using text-based syntax. Built on the powerful [Mermaid](https://mermaid.js.org/#/) JavaScript library, this widget transforms simple text descriptions into professional-quality diagrams, including flowcharts, sequence diagrams, Gantt charts, class diagrams, and more. The widget is particularly valuable for documenting experimental workflows, process flows, project timelines, and system architectures without requiring specialized diagramming software. With integrated AI assistance, users can generate complex diagrams from natural language descriptions, making diagram creation accessible to both technical and non-technical laboratory staff.

## Use Cases

* **Experimental Protocol Visualization**: Create flowcharts documenting step-by-step experimental procedures with decision points and conditional branches
* **Laboratory Workflow Mapping**: Design process flow diagrams showing sample handling, testing sequences, and quality control checkpoints
* **Project Timeline Management**: Build Gantt charts for research projects, showing task dependencies and milestone tracking

## Interface

### Read-only View

The read-only view displays the rendered diagram in its final visual form. Users can view the complete diagram with all formatting, colors, and styling applied according to the selected theme. The diagram is fully interactive, allowing users to zoom and pan when viewing complex or large diagrams. Any hyperlinks embedded within diagram elements are clickable, enabling navigation to related documentation or external resources. The view automatically scales diagrams to fit within the section container while maintaining aspect ratio and clarity.

<figure><img src="https://3607108856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LHVg57XIRcjV-Vbubtn%2Fuploads%2FE58vFPKnmDpjQjSHaw8V%2Fwidget-section-mermaid-readonly.webp?alt=media&#x26;token=be069f6b-9f28-415e-83fa-39cb3ca43992" alt="" width="230"><figcaption></figcaption></figure>

### Edit View

The edit view provides a split-screen interface with a text editor on the left and a live preview pane on the right. As users type or modify the Mermaid syntax, the preview updates in real-time, allowing immediate visualization of changes. The text editor includes syntax highlighting for Mermaid code, making it easier to identify diagram elements, relationships, and formatting directives.

<figure><img src="https://3607108856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LHVg57XIRcjV-Vbubtn%2Fuploads%2F4ds086zAfZsQ7YR0Uyt0%2Fwidget-section-mermaid-edit.webp?alt=media&#x26;token=9e12cfba-fff2-487d-b0e2-24431d8a01e4" alt=""><figcaption></figcaption></figure>

Key features of the edit interface include:

* **Code Editor**: Write or edit Mermaid syntax with line numbering and basic text editing capabilities
* **Live Preview**: Real-time rendering of diagrams as you type, showing exactly how the final diagram will appear
* **AI Assistant**: Access AI-powered diagram generation through a dedicated button, allowing natural language description of desired diagrams
* **Theme Selection**: Choose from multiple visual themes (Default, Forest, Dark, Neutral) to match documentation style or organizational branding
* **Insert/Replace Controls**: When using AI generation, choose to insert generated code at cursor position or replace existing content entirely
* **Syntax Validation**: Automatic detection of syntax errors with helpful error messages to guide corrections

The editor supports all standard text editing operations including copy, paste, undo, and redo, making it easy to iterate on diagram designs and incorporate feedback.

## Configuration

{% hint style="info" %}
The Mermaid widget requires minimal configuration to use. Most users can start creating diagrams immediately after adding the widget to a section.
{% endhint %}

### Adding the Mermaid Widget

{% stepper %}
{% step %}
Navigate to the record where you want to add a diagram and click **Add Section**
{% endstep %}

{% step %}
Select **Mermaid** from the section widget options
{% endstep %}

{% step %}
Click **Edit** to open the diagram editor and begin creating your diagram
{% endstep %}
{% endstepper %}

### Creating a Basic Diagram

{% stepper %}
{% step %}
In the edit view, enter your Mermaid syntax in the text editor. For a simple flowchart:

```
graph TD
    A[Start] --> B[Process Sample]
    B --> C{Quality Check}
    C -->|Pass| D[Continue Analysis]
    C -->|Fail| E[Reprocess]
    E --> B
```

{% endstep %}

{% step %}
Select your preferred theme from the theme dropdown:

* **Default**: Clean, minimalist styling with blue accents
* **Forest**: Green color palette suitable for environmental or biological documentation
* **Dark**: High contrast dark theme for presentations or reduced eye strain
* **Neutral**: Grayscale professional styling for formal documentation
  {% endstep %}

{% step %}
Click **Submit** to save the diagram. The rendered diagram will display in read-only view
{% endstep %}
{% endstepper %}

### Using AI Assistant to Generate Diagrams

{% stepper %}
{% step %}
Click the **AI Assistant** button in the diagram editor
{% endstep %}

{% step %}
Describe your desired diagram in natural language. Example: "Create a flowchart showing a protein purification workflow with centrifugation, column chromatography, and quality control steps"
{% endstep %}

{% step %}
Press **Enter** to submit your prompt
{% endstep %}

{% step %}
Review the AI-generated Mermaid code in the preview pane. The AI will create syntactically correct Mermaid code based on your description
{% endstep %}

{% step %}
Choose your insertion method:

* Click **Insert** to add the generated code at the current cursor position
* Click **Replace** to replace all existing diagram code with the generated version
  {% endstep %}

{% step %}
Refine the generated code as needed and select your preferred theme
{% endstep %}

{% step %}
Click **Submit** to save the completed diagram
{% endstep %}
{% endstepper %}

{% hint style="success" %}
The AI Assistant is particularly helpful for users unfamiliar with Mermaid syntax or when creating complex diagrams quickly. You can always edit the AI-generated code to customize the diagram further.
{% endhint %}

## Additional Functions

### Supported Diagram Types

The Mermaid widget supports all diagram types available in the Mermaid library:

#### Flowcharts

Standard directed graph diagrams for representing processes, decisions, and workflows. Supports multiple orientations (top-down, left-right, bottom-up) and various node shapes (rectangles, rounded rectangles, circles, diamonds, hexagons).

**Documentation**: <https://mermaid-js.github.io/mermaid/#/flowchart>

#### Sequence Diagrams

Interaction diagrams showing how processes, systems, or objects communicate with one another and in what order. Ideal for documenting system integrations, API interactions, and multi-step automated workflows.

**Documentation**: <https://mermaid-js.github.io/mermaid/#/sequenceDiagram>

#### Class Diagrams

Object-oriented modeling diagrams showing system structure, class relationships, and data models. Useful for documenting software architecture, database schemas, and data relationship models.

**Documentation**: <https://mermaid-js.github.io/mermaid/#/classDiagram>

#### State Diagrams

Diagrams describing system behavior through finite states and transitions. Excellent for documenting equipment states, sample lifecycle stages, and process control logic.

**Documentation**: <https://mermaid-js.github.io/mermaid/#/stateDiagram>

#### Gantt Charts

Project schedule visualizations showing task timelines, dependencies, and milestones. Essential for research project planning, resource allocation, and deadline tracking.

**Documentation**: <https://mermaid-js.github.io/mermaid/#/gantt>

#### Pie Charts

Circular statistical graphics displaying numerical proportions. Useful for visualizing resource allocation, sample composition, or categorical data distributions.

**Documentation**: <https://mermaid-js.github.io/mermaid/#/pie>

{% hint style="info" %}
Additional diagram types including entity relationship diagrams, user journey maps, and Git graphs are also supported. Check the Mermaid documentation for the complete list of available diagram types.
{% endhint %}

## References

### Official Mermaid Resources

* [Mermaid Official Documentation](https://mermaid.js.org/#/) - Comprehensive syntax guide and examples
* [Mermaid Live Editor](https://mermaid.live/) - Online tool for testing and developing Mermaid diagrams before adding to Labii
* [Mermaid GitHub Repository](https://github.com/mermaid-js/mermaid) - Source code, issue tracking, and community discussions

### Diagram Type References

* [Flowchart Syntax](https://mermaid-js.github.io/mermaid/#/flowchart) - Complete flowchart creation guide
* [Sequence Diagram Syntax](https://mermaid-js.github.io/mermaid/#/sequenceDiagram) - Interaction diagram documentation
* [Class Diagram Syntax](https://mermaid-js.github.io/mermaid/#/classDiagram) - Object-oriented modeling reference
* [State Diagram Syntax](https://mermaid-js.github.io/mermaid/#/stateDiagram) - State machine documentation
* [Gantt Chart Syntax](https://mermaid-js.github.io/mermaid/#/gantt) - Project timeline creation guide
* [Pie Chart Syntax](https://mermaid-js.github.io/mermaid/#/pie) - Proportional visualization reference