Skip to main content

Adding Diagrams to Documentation

This guide shows you how to add Mermaid diagrams to VeriMe documentation pages. Mermaid is built directly into Docusaurus, making it fast, reliable, and easy to use.

Quick Start​

Step 1: Write Your Mermaid Diagram​

Use Mermaid syntax to create your diagram. Here's a simple example:

```mermaid
graph LR
    User[User] --> Web[Web App]
    Web --> API[API]
    API --> DB[(Database)]
```

Step 2: Add to Your Markdown File​

Simply paste the Mermaid code block into your markdown file. Docusaurus will automatically render it.

Step 3: Preview​

Run the development server to see your diagram:

npm run start

The diagram will be rendered inline in your documentation page!

Diagram Types​

Flowcharts​

Perfect for showing processes, API flows, and decision trees:

Code:

```mermaid
flowchart TD
    Start([Start]) --> Input[Receive Request]
    Input --> Validate{Valid Input?}
    Validate -->|Yes| Process[Process Request]
    Validate -->|No| Error[Return 400 Error]
    Process --> Success[Return 200 OK]

    style Start fill:#A3D5FF
    style Success fill:#90EE90
    style Error fill:#FFB6C1
```

Flowchart Shapes:

  • [] - Rectangle (process)
  • {} - Diamond (decision)
  • () - Rounded rectangle
  • ([]) - Stadium (start/end)
  • [()] - Cylinder (database)

Sequence Diagrams​

Ideal for user interactions and API calls:

Code:

```mermaid
sequenceDiagram
    actor User
    participant Web as Web App
    participant API as API Gateway
    participant DB as Database

    User->>Web: Login Request
    activate Web
    Web->>API: Authenticate
    activate API
    API->>DB: Verify Credentials
    activate DB
    DB-->>API: User Found
    deactivate DB
    API-->>Web: Auth Token
    deactivate API
    Web-->>User: Success
    deactivate Web
```

Arrow Types:

  • -> - Solid line (synchronous)
  • --> - Dotted line (response)
  • ->> - Solid arrow (message)
  • -->> - Dotted arrow (return)

State Diagrams​

Useful for showing voucher or verification lifecycles:

Architecture Diagrams​

Great for showing system components and relationships:

Using VeriMe Brand Colors​

Apply VeriMe's brand colors to your diagrams for consistency:

VeriMe Brand Colors:

  • Primary Purple: #141571
  • Light Blue: #7FB4F0
  • Orange: #E79236
  • White: #FFFFFF

Using with CSS classes:

```mermaid
flowchart LR
    A[Component]
    B[Service]
    C[(Database)]

    A --> B --> C

    classDef primary fill:#f9f9f9,stroke:#141571,stroke-width:2px
    classDef data fill:#7FB4F0,stroke:#141571,stroke-width:2px
    classDef accent fill:#E79236,stroke:#141571,stroke-width:2px

    class A,B primary
    class C data
```

Advanced Features​

Adding Notes​

Use notes to provide additional context:

Subgraphs for Organization​

Group related components:

Complex Decision Trees​

Show multiple decision paths:

Best Practices​

1. Keep It Simple​

  • Focus on one concept per diagram
  • Avoid overcrowding with too many elements
  • Use multiple simple diagrams instead of one complex diagram

2. Add Clear Labels​

Use descriptive labels that match your documentation:

Better than:

3. Consistent Styling​

Use the same color scheme across all diagrams:

4. Use Appropriate Diagram Types​

  • Flowcharts - Processes and decision flows
  • Sequence - Time-ordered interactions
  • State - Lifecycle and state transitions
  • Graph - Architecture and relationships

5. Test Before Committing​

Always preview your diagram before committing:

  1. Save your markdown file
  2. Run npm run start
  3. Navigate to the page
  4. Verify the diagram renders correctly

Mermaid Syntax Reference​

Flowchart Direction​

flowchart TD  %% Top to bottom
flowchart LR  %% Left to right
flowchart RL  %% Right to left
flowchart BT  %% Bottom to top

Node Shapes​

Arrow Types​

Styling​

style NodeId fill:#color,stroke:#color,stroke-width:2px

Troubleshooting​

Diagram Not Rendering​

Problem: Code block shows as text instead of rendering

Solutions:

  • Ensure you're using ```mermaid (not ```mer or ```Mermaid)
  • Check that the syntax is valid
  • Try testing your diagram at Mermaid Live Editor

Syntax Errors​

Problem: Diagram shows error message

Solutions:

  • Validate syntax using the online Mermaid editor
  • Check for missing quotes in labels with special characters
  • Verify arrow syntax (->, -->, etc.)
  • Ensure proper indentation in subgraphs

Styling Not Applied​

Problem: Colors or styling don't appear

Solutions:

  • Place style directives after diagram elements
  • Use valid hex color codes (with # prefix)
  • Check for typos in node IDs
  • Test without styling first, then add incrementally

Complex Diagrams Load Slowly​

Problem: Page performance issues

Solutions:

  • Break complex diagrams into smaller ones
  • Simplify by removing unnecessary details
  • Consider using multiple pages for extensive documentation

Resources​

Next Steps​