The Ultimate Guide to Automating Diagram Creation with ChatGPT and Mermaid Code

What is Mermaid?

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. I've found it to be incredibly valuable for technical documentation because it allows diagrams to be version-controlled alongside code and maintained using the same workflows.

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
                                

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
                                    

ChatGPT's Role in Diagram Generation

I've discovered that ChatGPT can generate complex Mermaid diagram code through carefully crafted prompts. This powerful capability transforms the way we create technical diagrams by allowing us to describe what we want in natural language and receive functional diagram code in return.

The relationship between natural language instructions and diagram code generation is fascinating. ChatGPT interprets your descriptive intent and translates it into structured Mermaid syntax. This is particularly valuable for those who understand the diagrams they need but lack familiarity with Mermaid's specific syntax requirements.

Benefits of Automated Diagram Creation

When I compare automated diagram generation to manual coding or visual tools, I find several compelling advantages:

• Speed: Generate complex diagrams in seconds rather than spending hours manually coding or drawing
• Accessibility: Create professional diagrams without needing to learn Mermaid syntax
• Iteration: Quickly refine diagrams through conversational prompts
• Integration: Easily incorporate generated code into documentation workflows
• Consistency: Maintain uniform diagram styles across documentation

Essential Prompt Structures

Through extensive experimentation, I've developed several prompt structures that consistently yield accurate Mermaid code. The key is to be specific about both the diagram type and the relationships you want to illustrate.

"Generate a Mermaid [DIAGRAM_TYPE] that shows [SPECIFIC_DESCRIPTION]. 
Include the following elements: [ELEMENT1, ELEMENT2, ...] 
with these relationships: [RELATIONSHIP_DESCRIPTIONS].
Use the following styling: [STYLING_PREFERENCES]."
                        

When write effective AI prompts for diagram generation, I always make sure to include clear instructions about the diagram's purpose and audience. This context helps ChatGPT generate more relevant and useful visualizations.

Specifying Diagram Types

flowchart TD
    subgraph "Mermaid Diagram Types"
        flow[Flowchart] 
        seq[Sequence Diagram]
        class[Class Diagram]
        state[State Diagram]
        er[Entity Relationship]
        gantt[Gantt Chart]
        pie[Pie Chart]
        git[Git Graph]
    end
    flow --> direction["Direction: TD, LR, RL, BT"]
    seq --> actors["Actors & Messages"]
    class --> relations["Classes & Relations"]
    state --> transitions["States & Transitions"]
    er --> entities["Entities & Relationships"]
    gantt --> tasks["Tasks & Timeline"]
    pie --> values["Values & Labels"]
    git --> commits["Commits & Branches"]
                        

Each diagram type requires specific terminology in your prompts. I've found it helpful to explicitly state the diagram type at the beginning of my prompt and then use the appropriate vocabulary for that type.

Common Pitfalls and Solutions

PageOn.ai's Deep Search functionality has been invaluable in my work with Mermaid diagrams. I use it to find relevant diagram examples and patterns that I can reference in my prompts to ChatGPT, which significantly improves the quality and accuracy of the generated code.

Creating Multi-level Flowcharts

For complex systems, I often need to create multi-level flowcharts that clearly show hierarchies and relationships. I've found that using subgraphs in Mermaid is the key to organizing these complex diagrams.

flowchart TD
    subgraph "Client Layer"
        A[Web Browser]
        B[Mobile App]
    end
    subgraph "API Layer"
        C[API Gateway]
        D[Authentication]
        E[Rate Limiting]
    end
    subgraph "Service Layer"
        F[User Service]
        G[Content Service]
        H[Analytics Service]
    end
    subgraph "Data Layer"
        I[(User DB)]
        J[(Content DB)]
        K[(Analytics DB)]
    end
    A --> C
    B --> C
    C --> D
    C --> E
    D --> F
    E --> F
    E --> G
    E --> H
    F --> I
    G --> J
    H --> K
                            

Designing Sequence Diagrams

Sequence diagrams are excellent for visualizing interactions between different components over time. I've developed specific prompting techniques to ensure these diagrams accurately capture the temporal flow of operations.

sequenceDiagram
    participant User
    participant App
    participant API
    participant DB
    User->>App: Opens application
    App->>API: Request user data
    API->>DB: Query user information
    DB-->>API: Return user data
    API-->>App: Send user profile
    App-->>User: Display dashboard
    User->>App: Create new item
    App->>API: Send item data
    API->>DB: Insert new record
    DB-->>API: Confirm success
    API-->>App: Return item ID
    App-->>User: Show confirmation
                        

When prompting for sequence diagrams, I've found it helpful to explicitly list all actors first, then describe each interaction step-by-step in chronological order. This approach helps ChatGPT generate more accurate sequence flows.

Entity-Relationship Diagrams

For database design visualization, entity-relationship diagrams are invaluable. I use specific terminology in my prompts to ensure the relationships are correctly represented.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string email
        string address
    }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int order_id
        date created_at
        string status
    }
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    PRODUCT {
        int product_id
        string name
        float price
        string category
    }
    ORDER_ITEM {
        int quantity
        float price
    }
                        

For ER diagrams, I make sure to specify cardinality relationships (one-to-many, many-to-many, etc.) and include the attributes for each entity. This level of detail helps ChatGPT generate more useful and accurate database diagrams.

Specifying Styling Preferences

One of the most powerful aspects of Mermaid diagrams is the ability to customize their appearance. I've developed specific prompt techniques to control colors, shapes, and styles.

flowchart TD
    classDef start fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#28a745,rx:10,ry:10
    classDef process fill:#f8f9fa,stroke:#6c757d,stroke-width:1px
    classDef success fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#28a745,shape:hexagon
    classDef error fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#dc3545,shape:hexagon
    A[Start] --> B[Fill Registration Form]
    B --> C{Validate Input}
    C -->|Valid| D[Create Account]
    C -->|Invalid| E[Show Error Message]
    D --> F[Success: Account Created]
    E --> B
    A:::start
    B:::process
    C:::process
    D:::process
    E:::error
    F:::success
                        

I've found that being specific about colors (using named colors or hex codes), shapes, and line styles in my prompts leads to much more visually appealing and informative diagrams.

Controlling Node Shapes and Relationships

flowchart TD
    A[Rectangle]
    B(Rounded Rectangle)
    C([Stadium shape])
    D[[Subroutine shape]]
    E[(Database)]
    F((Circle))
    G>Asymmetric]
    H{Diamond}
    I{{Hexagon}}
    J[/Parallelogram/]
    K[\Parallelogram alt\]
    L[/Trapezoid\]
    M[\Trapezoid alt/]
                                

flowchart LR
    A1[Normal] --> B1[Arrow]
    A2[Open] --- B2[Link]
    A3[Bold] ==> B3[Arrow]
    A4[Dotted] -.-> B4[Arrow]
    A5[Dotted] -.- B5[Link]
    A6[Text] -->|Yes| B6[On Link]
    A7[Two-way] <--> B7[Arrow]
                                

When creating diagrams for technical documentation, I use specific node shapes to represent different types of components. For example, I use database shapes for data stores, diamonds for decision points, and rectangles for processes. This visual language makes the diagrams more intuitive.

I've found that integrating these styling requirements with ChatGPT generate AI images capabilities creates a powerful workflow for generating both diagrams and supporting visuals that share a consistent visual language.

Documentation Platform Integration

I've developed specific prompting techniques for generating Mermaid code that integrates seamlessly with various documentation platforms.

```mermaid
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
```
                            

<ac:structured-macro ac:name="mermaid">
<ac:plain-text-body><![CDATA[
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
]]></ac:plain-text-body>
</ac:structured-macro>
                            

When generating diagrams for specific platforms, I include the platform name in my prompt: "Generate a Mermaid flowchart for GitHub markdown that shows..." This ensures ChatGPT produces code in the correct format.

Iterative Refinement Techniques

I've found that diagram creation is rarely a one-shot process. Instead, I use an iterative approach with ChatGPT:

1. Start with a basic prompt describing the diagram's purpose and key elements
2. Review the generated code and identify areas for improvement
3. Ask for specific modifications: "Please update the diagram to add a new node for payment processing between the Order and Confirmation steps"
4. Request styling enhancements once the structure is correct
5. Finally, ask for the code in the format needed for your documentation platform

Creating Prompt Templates

To ensure consistency across my team, I've created a set of prompt templates for different diagram types. These templates include placeholders for specific content while maintaining a consistent structure and style.

"Generate a Mermaid flowchart with top-down direction showing the system architecture for [SYSTEM_NAME]. 
Include these components:
- Frontend: [LIST_FRONTEND_COMPONENTS]
- Backend: [LIST_BACKEND_SERVICES]
- Databases: [LIST_DATABASES]
- External Services: [LIST_EXTERNAL_SERVICES]
Show the data flow between components with these key interactions:
[LIST_KEY_INTERACTIONS]
Use the following styling:
- Frontend components: rounded rectangles with light blue background
- Backend services: regular rectangles with light green background
- Databases: cylinder shape with light yellow background
- External services: hexagons with light purple background
- Arrows should indicate data flow direction"
                        

Using AI chat tools for coding in combination with these templates has dramatically improved my team's efficiency in creating technical documentation.

System Architecture Visualization

I recently needed to create a comprehensive system architecture diagram for a microservice-based application. Here's how I approached it:

flowchart LR
    %% Client Applications
    WebClient([Web Client]):::client
    MobileApp([Mobile App]):::client
    %% API Layer
    Gateway[API Gateway]:::service
    %% Microservices
    UserService[User Service]:::service
    ProductService[Product Service]:::service
    OrderService[Order Service]:::service
    PaymentService[Payment Service]:::service
    NotificationService[Notification Service]:::service
    %% Databases
    UserDB[(User DB)]:::database
    ProductDB[(Product DB)]:::database
    OrderDB[(Order DB)]:::database
    %% External Systems
    PaymentProvider{{Payment Provider}}:::external
    %% Connections
    WebClient --> Gateway
    MobileApp --> Gateway
    Gateway --> UserService
    Gateway --> ProductService
    Gateway --> OrderService
    UserService --> UserDB
    ProductService --> ProductDB
    OrderService --> OrderDB
    OrderService --> PaymentService
    OrderService --> NotificationService
    PaymentService --> PaymentProvider
    NotificationService --> UserService
    %% Highlight Order Flow
    WebClient -.-> |1. Browse Products| Gateway
    Gateway -.-> |2. Get Products| ProductService
    ProductService -.-> |3. Fetch Products| ProductDB
    WebClient -.-> |4. Place Order| Gateway
    Gateway -.-> |5. Create Order| OrderService
    OrderService -.-> |6. Save Order| OrderDB
    OrderService -.-> |7. Process Payment| PaymentService
    PaymentService -.-> |8. External Payment| PaymentProvider
    OrderService -.-> |9. Send Notification| NotificationService
    %% Styles
    classDef client fill:#d4f1f9,stroke:#05a5d1,stroke-width:2px,rx:10,ry:10
    classDef service fill:#d5f5e3,stroke:#2ecc71,stroke-width:1px
    classDef database fill:#fef9e7,stroke:#f1c40f,stroke-width:1px
    classDef external fill:#ebdef0,stroke:#8e44ad,stroke-width:1px
                            

This case demonstrates how a well-structured prompt can generate a complex system architecture diagram that clearly shows both the overall structure and a specific flow (in this case, the order placement process).

User Journey Visualization

Converting user journey narratives into visual flowcharts helps product teams understand the user experience. Here's an example:

flowchart TD
    Start([User starts]) --> Discover[Discovers product]
    Discover --> Research[Researches features]
    Research --> Compare{Compare alternatives?}
    Compare -->|Yes| Competitors[Views competitors]
    Competitors --> Decision
    Compare -->|No| Decision{Make decision}
    Decision -->|Purchase| Checkout[Proceeds to checkout]
    Decision -->|Abandon| Exit([Exits journey])
    Checkout --> Payment[Completes payment]
    Payment --> Confirmation[Receives confirmation]
    Confirmation --> Onboarding[Completes onboarding]
    Onboarding --> Usage[Regular usage]
    Usage --> Feedback[Provides feedback]
    classDef start fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#212529,rx:10,ry:10
    classDef process fill:#f8f9fa,stroke:#6c757d,stroke-width:1px,color:#212529
    classDef decision fill:#e2f0fd,stroke:#0d6efd,stroke-width:1px,color:#212529,shape:diamond
    classDef end fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#212529,rx:10,ry:10
    Start:::start
    Discover:::process
    Research:::process
    Compare:::decision
    Competitors:::process
    Decision:::decision
    Checkout:::process
    Payment:::process
    Confirmation:::process
    Onboarding:::process
    Usage:::process
    Feedback:::process
    Exit:::end
                        

To create this diagram, I provided ChatGPT with a narrative description of the user journey and asked it to visualize the flow with decision points and possible paths. The prompt included specific instructions for color-coding different types of steps in the journey.

Common Errors and Solutions

I've found that most errors in generated Mermaid code can be fixed by providing more specific instructions or examples of the correct syntax in follow-up prompts.

Breaking Down Complex Diagrams

When dealing with complex systems, I've found it's much more effective to break them down into multiple connected diagrams rather than trying to create one massive visualization. This approach has several benefits:

• Improved readability and focus on specific aspects of the system
• Higher success rate in generating correct code
• Better rendering performance in documentation platforms
• Easier maintenance and updates
• More accurate representation of specific components

For example, instead of creating one massive system architecture diagram, I might create separate diagrams for the frontend architecture, backend services, data flow, and deployment infrastructure, with clear references between them.

Staying Updated with Mermaid

Mermaid is an actively developed tool with regular updates and new features. To keep my diagram generation prompts effective, I follow these practices:

• Subscribe to the Mermaid.js GitHub repository for release notifications
• Periodically review the documentation for syntax changes
• Test existing prompt templates with new Mermaid versions
• Explore new diagram types as they become available

When a new Mermaid feature is released, I explicitly mention it in my prompts to ensure ChatGPT incorporates it correctly: "Generate a Mermaid diagram using the new journey chart type introduced in version X.X..."

Adapting Prompts for Different AI Models

Different AI models have varying capabilities when it comes to generating Mermaid code. I've developed strategies for adapting my prompts based on the model I'm using:

Building a Prompt Library

One of the most valuable practices I've developed is maintaining a library of successful prompting patterns. This includes:

• Template prompts for each diagram type
• Successful examples with both the prompt and resulting code
• Styling patterns that work well for different contexts
• Troubleshooting prompts for common errors

This library serves as a valuable resource for my team and helps maintain consistency across our documentation.