# Mermaid Sequence Diagrams in Confluence: FAQ & Examples May 2, 2026 · 17 min read [NGPilot](https://ngpilot.com) Sequence diagrams are one of the most widely used diagram types in software documentation. They show exactly how participants -- users, services, databases, external APIs -- exchange messages over time. For Confluence teams, embedding sequence diagrams directly on wiki pages means architecture docs, API specifications, and incident post-mortems stay in one place instead of scattered across external tools. Mermaid's text-based syntax makes sequence diagrams fast to write and easy to update, but the syntax has its own set of rules that can trip you up. This FAQ answers the questions Confluence users ask most often about building sequence diagrams with Mermaid, with expanded explanations, working code examples, and copy-paste templates you can drop straight into a Mermaid Plus macro. ## How do I create a sequence diagram in Confluence with Mermaid?[​](#how-do-i-create-a-sequence-diagram-in-confluence-with-mermaid "Direct link to How do I create a sequence diagram in Confluence with Mermaid?") Creating a sequence diagram in Confluence requires two things: a Mermaid-compatible macro on the page and the correct `sequenceDiagram` syntax in the macro body. Here is the step-by-step process. **Step 1: Install Mermaid Plus for Confluence.** Go to the Atlassian Marketplace, search for **Mermaid Plus for Confluence**, and click **Get App**. If your organization requires admin approval for marketplace apps, submit a request through your internal process. Once installed, the macro is available in every Confluence space. **Step 2: Insert the macro on a page.** Open any Confluence page in edit mode. Type `/mermaid` in the editor and select the **Mermaid Plus** macro from the dropdown. A code editor panel opens where you can write and preview your diagram. **Step 3: Write the sequence diagram code.** Start with the `sequenceDiagram` keyword, declare your participants, and add messages between them: ``` sequenceDiagram participant Client participant API as API Gateway participant DB as Database Client->>API: POST /users API->>DB: INSERT INTO users DB-->>API: Row created API-->>Client: 201 Created ``` **Step 4: Preview and publish.** Click **Preview** inside the macro editor to verify the diagram renders correctly. When you are satisfied, click **Save** on the macro, then **Publish** the Confluence page. The `participant` keyword is optional -- Mermaid will infer participants from the message lines -- but declaring them explicitly gives you control over the display order and lets you use the `as` keyword to set friendly display names while keeping short aliases in the code. ## What arrow types does Mermaid support in sequence diagrams?[​](#what-arrow-types-does-mermaid-support-in-sequence-diagrams "Direct link to What arrow types does Mermaid support in sequence diagrams?") Arrow types are the most important visual cue in a sequence diagram. Different arrow styles communicate different types of interactions, and using them consistently makes your diagrams immediately understandable. Mermaid supports six distinct arrow operators for sequence diagrams: | Arrow Type | Syntax | Meaning | When to Use | | -------------------------- | -------------- | ---------------------- | -------------------------------------- | | Solid arrow with message | `A->>B: Text` | Synchronous request | Direct calls, RPCs, form submissions | | Dashed arrow with message | `A-->>B: Text` | Response or return | Return values, acknowledgments | | Solid open arrow | `A-)B: Text` | Asynchronous message | Event emissions, fire-and-forget calls | | Dashed open arrow | `A--)B: Text` | Asynchronous return | Callback completions | | Solid line (no arrowhead) | `A-B: Text` | Flat connection | General association | | Dashed line (no arrowhead) | `A--B: Text` | Dashed flat connection | Weak or indirect association | Here is an example that uses both solid and dashed arrows to distinguish between requests and responses: ``` sequenceDiagram participant User participant Web as Web App participant Auth as Auth Service participant DB as User Store User->>Web: Login with credentials Web->>Auth: Validate credentials Auth->>DB: Lookup user record DB-->>Auth: User data Auth-->>Web: JWT token Web-->>User: Dashboard loaded ``` A common convention is to use `->>` for all outgoing requests and `-->>` for all responses. This creates a clear visual rhythm where solid lines go left-to-right (or top-to-bottom) and dashed lines come back. Your team should agree on a convention and apply it consistently across all sequence diagrams in your documentation. ## How do I add conditional logic (if/else) in Mermaid sequence diagrams?[​](#how-do-i-add-conditional-logic-ifelse-in-mermaid-sequence-diagrams "Direct link to How do I add conditional logic (if/else) in Mermaid sequence diagrams?") Real-world interactions are rarely linear. Conditional branches -- where the flow diverges based on a condition -- are modeled in Mermaid using `alt`/`else`/`end` blocks. Every `alt` block must be closed with an `end` keyword, and you can include one or more `else` sections for alternative paths. Here is a basic `alt`/`else` block: ``` sequenceDiagram participant User participant API as Payment API participant Bank as Bank Gateway User->>API: Process payment API->>Bank: Charge card alt Charge succeeds Bank-->>API: 200 OK, charge_id API-->>User: Payment confirmed else Charge declined Bank-->>API: 402 Declined API-->>User: Payment failed end ``` You can also nest `alt` blocks for multi-level conditional logic. For example, a payment flow might first check whether the card is valid, then check whether sufficient funds are available: ``` sequenceDiagram participant User participant API as Payment API participant Bank as Bank Gateway User->>API: Process payment API->>Bank: Validate and charge alt Card is valid Bank->>Bank: Check balance alt Sufficient funds Bank-->>API: Charge successful API-->>User: Payment confirmed else Insufficient funds Bank-->>API: Insufficient funds API-->>User: Payment declined - low balance end else Card declined Bank-->>API: Card rejected API-->>User: Invalid card details end ``` For optional steps that have no alternative -- meaning they may or may not happen -- use the `opt` block instead of `alt`: ``` sequenceDiagram participant Client participant API as API Client->>API: Place order API-->>Client: Order confirmed opt User is premium member API->>API: Apply discount API-->>Client: Discount applied end ``` A few things to watch for when working with conditional blocks: * Every `alt` must have exactly one matching `end`. Count them carefully before publishing. * You cannot use `else` outside of an `alt` block. * `opt` blocks do not take an `else` clause because they represent an optional step, not a branching choice. ## Can I add loops in Mermaid sequence diagrams?[​](#can-i-add-loops-in-mermaid-sequence-diagrams "Direct link to Can I add loops in Mermaid sequence diagrams?") Yes. Loops are one of the most useful constructs in sequence diagrams because they let you model retry logic, polling intervals, batch processing, and any other repeated interaction. Mermaid uses the `loop` keyword followed by a description and closed with `end`. Here is a basic loop that models a client polling a server for job status: ``` sequenceDiagram participant Client participant Server as Job Server Client->>Server: Submit job Server-->>Client: Job ID: 12345 loop Poll every 5 seconds Client->>Server: GET /jobs/12345 Server-->>Client: Status: processing end Client->>Server: GET /jobs/12345 Server-->>Client: Status: complete ``` The rendered diagram draws a labeled rectangle around the messages inside the loop block, making it visually distinct from the surrounding flow. The description text appears as a label in the top-left corner of the rectangle. Loops are frequently combined with `alt` blocks to model retry-with-fallback patterns: ``` sequenceDiagram participant Client participant Service as Downstream Service Client->>Service: Send request alt Service responds Service-->>Client: 200 OK else Service times out loop Retry up to 3 times Client->>Service: Retry request alt Success on retry Service-->>Client: 200 OK else Still failing Note right of Client: Wait 2s, then retry end end end ``` You can nest loops inside `alt` blocks and vice versa, but be careful with deeply nested structures. Each nesting level adds complexity and makes the diagram harder to read. If you find yourself going three or more levels deep, consider splitting the diagram into two separate diagrams and linking them with descriptive text. ## How do I add notes to a Mermaid sequence diagram?[​](#how-do-i-add-notes-to-a-mermaid-sequence-diagram "Direct link to How do I add notes to a Mermaid sequence diagram?") Notes let you annotate specific participants or spans of the diagram with contextual information that does not belong in the message flow itself. Mermaid supports three note placement options: * `Note left of A: Text` -- places a note to the left of participant A * `Note right of A: Text` -- places a note to the right of participant A * `Note over A,B: Text` -- places a note spanning from participant A to participant B Here is an example that uses all three: ``` sequenceDiagram participant Client participant API as API Gateway participant DB as Database Note left of Client: Mobile app user Client->>API: GET /products Note over Client,API: TLS 1.3 encrypted API->>DB: SELECT * FROM products DB-->>API: Result set API-->>Client: JSON response Note right of DB: Read replica ``` Notes are best used for annotations that help a reader understand the diagram without cluttering the message arrows. Good candidates for notes include: * Security annotations (encrypted connections, authentication method) * Infrastructure context (read replica, cache layer, load balancer) * Business rules that apply to a specific step * SLA or performance targets for a particular call * References to external documentation or runbooks Avoid using notes for information that belongs in the message labels themselves. If you find yourself writing a note that says "Client sends a login request," put that information in the arrow label instead: `Client->>API: POST /auth/login`. Notes should add information that is not already conveyed by the message flow. For multiline notes, Mermaid does not support explicit line breaks within a single `Note` statement in all versions. If you need a longer annotation, consider placing it in the surrounding Confluence text rather than inside the diagram. ## Why is my sequence diagram not rendering in Confluence?[​](#why-is-my-sequence-diagram-not-rendering-in-confluence "Direct link to Why is my sequence diagram not rendering in Confluence?") When a sequence diagram shows raw code instead of a rendered diagram, or when it renders partially and then stops, the cause is almost always a syntax error. Here are the most common issues and how to fix each one. **Missing `sequenceDiagram` keyword.** Every Mermaid sequence diagram must begin with the `sequenceDiagram` keyword on its own line. Without it, Mermaid does not know what type of diagram to render. ``` sequenceDiagram participant A as Alice participant B as Bob A->>B: Hello ``` **Unclosed `alt` or `loop` blocks.** Every `alt`, `opt`, `loop`, `par`, and `critical` block must have a matching `end`. If you open three blocks, you need three `end` statements. Missing `end` keywords are the single most common cause of failed renders. ``` %% INCORRECT -- missing end alt Condition A A->>B: Action else Condition B A->>B: Other action %% No end keyword! %% CORRECT alt Condition A A->>B: Action else Condition B A->>B: Other action end ``` **Special characters in labels not wrapped in quotes.** If a message label contains parentheses, brackets, or other special characters, wrap the label in double quotes: ``` %% INCORRECT A->>B: Send (urgent) message %% CORRECT A->>B: "Send (urgent) message" ``` **Missing colon before message text.** Every arrow must include a colon followed by the message text. Without the colon, Mermaid cannot parse the line: ``` %% INCORRECT A->>B Send data %% CORRECT A->>B: Send data ``` **The Mermaid macro is not installed or enabled.** If typing `/mermaid` in the Confluence editor does not show a macro option, the Mermaid Plus app may not be installed. Check **Confluence Administration > Apps** to verify the app is present and active. **The fastest way to debug.** Copy your Mermaid code and paste it into the [Mermaid Live Editor](https://mermaid.live). The Live Editor renders the diagram in real time and highlights the exact line where parsing fails. Fix the error in the Live Editor, then paste the corrected code back into Confluence. ## Sequence Diagram Syntax Quick Reference[​](#sequence-diagram-syntax-quick-reference "Direct link to Sequence Diagram Syntax Quick Reference") Keep this table handy when writing sequence diagrams in Confluence. It covers every commonly used syntax element. | Element | Syntax | Description | | --------------------- | ----------------------------- | -------------------------------------- | | Diagram type | `sequenceDiagram` | Required first line | | Participant | `participant A as Alice` | Declare a named participant with alias | | Actor | `actor User` | Stick-figure actor instead of box | | Solid message | `A->>B: Text` | Synchronous request or call | | Dashed message | `A-->>B: Text` | Response, return value, async reply | | Open arrow (solid) | `A-)B: Text` | Asynchronous message | | Open arrow (dashed) | `A--)B: Text` | Asynchronous return | | Note (left) | `Note left of A: Text` | Note to the left of a participant | | Note (right) | `Note right of A: Text` | Note to the right of a participant | | Note (spanning) | `Note over A,B: Text` | Note spanning multiple participants | | Conditional | `alt Cond ... else ... end` | If/else branching | | Optional | `opt Cond ... end` | Optional step, no else | | Loop | `loop Desc ... end` | Repeated interaction | | Parallel | `par ... and ... end` | Concurrent execution | | Critical | `critical ... option ... end` | Must-complete block with fallback | | Activate bar | `activate A` | Show active processing on participant | | Deactivate bar | `deactivate A` | Remove activation bar | | Shortcut activation | `A->>+B: Text` | Activate B automatically | | Shortcut deactivation | `A->>-B: Text` | Deactivate B automatically | | Auto-numbering | `autonumber` | Number messages sequentially | | Comment | `%% Text` | Inline comment, not rendered | | Delay | `...` | Visual delay/spacer in the timeline | | Background | `rect rgb(r,g,b) ... end` | Colored background for a section | ## Copy-Paste Sequence Diagram Examples[​](#copy-paste-sequence-diagram-examples "Direct link to Copy-Paste Sequence Diagram Examples") The following three examples are complete, ready to paste into a Mermaid Plus macro in Confluence. Modify the participants, messages, and labels to match your own architecture. ### Example 1: Authentication Flow with Token Refresh[​](#example-1-authentication-flow-with-token-refresh "Direct link to Example 1: Authentication Flow with Token Refresh") This diagram shows a full OAuth 2.0-style authentication flow including login, token issuance, resource access, and token refresh. It covers the happy path and the expired-token recovery path. ``` sequenceDiagram autonumber actor User participant FE as Frontend participant Auth as Auth Service participant Resource as Resource Server participant Cache as Token Store User->>FE: Enter email and password FE->>Auth: POST /auth/login {email, password} Auth->>Auth: Validate credentials alt Valid credentials Auth->>Cache: Store refresh token Auth-->>FE: 200 {access_token, refresh_token, expires_in} FE->>FE: Store tokens in memory FE-->>User: Redirect to dashboard Note over User,Resource: --- Subsequent API calls --- User->>FE: View profile FE->>Resource: GET /api/profile (Authorization: Bearer ) Resource->>Auth: Validate access token Auth-->>Resource: Token valid Resource-->>FE: 200 {user profile} FE-->>User: Display profile Note over User,Auth: --- Token expires after 1 hour --- User->>FE: View orders FE->>Resource: GET /api/orders (Authorization: Bearer ) Resource-->>FE: 401 Token expired FE->>Auth: POST /auth/refresh {refresh_token} Auth->>Cache: Verify refresh token Cache-->>Auth: Token valid Auth-->>FE: 200 {new_access_token} FE->>Resource: GET /api/orders (Authorization: Bearer ) Resource-->>FE: 200 {orders} FE-->>User: Display orders else Invalid credentials Auth-->>FE: 401 Unauthorized FE-->>User: Show error: Invalid email or password end ``` ### Example 2: Order Processing with Inventory and Payment[​](#example-2-order-processing-with-inventory-and-payment "Direct link to Example 2: Order Processing with Inventory and Payment") This diagram models an e-commerce order placement flow. It shows the synchronous calls to inventory and payment services, the event-driven notification, and the rollback path when payment fails. ``` sequenceDiagram autonumber participant Customer participant Web as Web App participant Order as Order Service participant Inv as Inventory Service participant Pay as Payment Service participant Bus as Event Bus participant Email as Email Service Customer->>Web: Place order Web->>Order: POST /orders {items, payment_method} activate Order Order->>Inv: POST /inventory/reserve {items} activate Inv alt Items in stock Inv-->>Order: 200 {reservation_id} deactivate Inv Order->>Pay: POST /payments/charge {amount, method} activate Pay alt Payment succeeds Pay-->>Order: 200 {charge_id} deactivate Pay Order->>Order: Create order record Order->>Bus: Publish order.created event Bus-->>Email: Deliver event Email->>Email: Send confirmation email Order-->>Web: 201 {order_id, status: confirmed} Web-->>Customer: Order confirmation page else Payment fails Pay-->>Order: 402 Payment declined deactivate Pay Order->>Inv: POST /inventory/release {reservation_id} Inv-->>Order: 200 Released Order-->>Web: 402 {error: payment_declined} Web-->>Customer: Payment failed, try again end else Items out of stock Inv-->>Order: 409 {error: insufficient_stock} deactivate Inv Order-->>Web: 409 Out of stock Web-->>Customer: Items unavailable end deactivate Order ``` ### Example 3: Error Handling with Retry and Circuit Breaker[​](#example-3-error-handling-with-retry-and-circuit-breaker "Direct link to Example 3: Error Handling with Retry and Circuit Breaker") This diagram illustrates a resilient client calling a downstream service through retry middleware and a circuit breaker. It covers the healthy path, the retry path, and the circuit-open fallback. ``` sequenceDiagram autonumber participant App as Application participant Retry as Retry Middleware participant CB as Circuit Breaker participant Svc as Downstream Service participant Fallback as Fallback Service App->>Retry: Send request Retry->>CB: Forward request alt Circuit is closed (healthy) CB->>Svc: Proxy request alt Service responds successfully Svc-->>CB: 200 OK CB->>CB: Record success CB-->>Retry: 200 OK Retry-->>App: Success response else Service returns 5xx Svc-->>CB: 503 Unavailable CB->>CB: Record failure loop Retry up to 3 times with exponential backoff Retry->>CB: Retry request CB->>Svc: Proxy request alt Retry succeeds Svc-->>CB: 200 OK CB-->>Retry: 200 OK else Retry fails Svc-->>CB: 503 Unavailable CB->>CB: Increment failure count end end alt At least one retry succeeded CB-->>Retry: 200 OK Retry-->>App: Success response else All retries exhausted CB->>CB: Open circuit CB->>Fallback: Request fallback response Fallback-->>CB: Cached or default data CB-->>Retry: Degraded response Retry-->>App: 200 with fallback data Note right of CB: Circuit stays open for 30s end end else Circuit is open (tripped) CB->>Fallback: Serve from cache Fallback-->>CB: Stale data CB-->>Retry: Degraded response Retry-->>App: 200 with cached data Note over CB: After 30s timeout, circuit goes to half-open end ``` ## Tips for Readable Sequence Diagrams[​](#tips-for-readable-sequence-diagrams "Direct link to Tips for Readable Sequence Diagrams") A sequence diagram is only useful if your team can read and understand it at a glance. These tips help you produce diagrams that communicate clearly. **Limit participants to five or six.** Each additional participant reduces the horizontal space available for message labels. If your architecture involves more than six actors, split the interaction into multiple diagrams. For example, diagram the client-to-gateway interaction separately from the gateway-to-backend interaction. **Use the `as` keyword for short aliases.** Write `participant AuthSvc as Authentication Service` in your code. This keeps the Mermaid source readable while displaying the full name in the rendered diagram. Short aliases also reduce the chance of typos when writing arrow statements. **Auto-number your messages.** Add `autonumber` on the line immediately after `sequenceDiagram`. Numbered messages give your team a shared vocabulary for discussing specific steps ("the issue is at step 4 where the API gateway times out"). **Be consistent with arrow conventions.** Agree with your team that solid arrows (`->>`) always represent requests and dashed arrows (`-->>`) always represent responses. Consistent visual language reduces the cognitive load of reading the diagram. **Add notes for non-obvious context.** Use `Note over A,B: Text` for cross-cutting concerns like encryption, rate limiting, or SLA boundaries. Place notes only where they add information that is not already in the message labels. **Split large diagrams by phase.** If a single diagram would exceed 20 to 25 messages, break it into phases. For example, split an order flow into "Order Placement," "Payment Processing," and "Fulfillment" diagrams. Link them with a brief prose description on the Confluence page. **Use `activate` and `deactivate` sparingly.** Activation bars show when a participant is actively processing a request. They add visual clarity to simple diagrams but create clutter in complex ones. Use them for the most important service interactions and omit them for trivial pass-through calls. **Test in the Mermaid Live Editor first.** Before pasting code into Confluence, validate it at [mermaid.live](https://mermaid.live). The Live Editor shows rendering errors in real time, which is faster than saving, publishing, and reloading a Confluence page to check each change. ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Mermaid Plus for Confluence](/apps/mermaid-plus-for-confluence.md) -- complete usage guide with configuration, themes, and all 29 supported diagram types * [How to Create Sequence Diagrams in Confluence](/blog/how-to-create-sequence-diagrams-confluence.md) -- step-by-step tutorial for building sequence diagrams from scratch * [Mermaid Syntax Cheat Sheet](/blog/faq-mermaid-syntax-cheat-sheet-confluence.md) -- quick reference for all Mermaid diagram types supported in Confluence * [Mermaid Troubleshooting FAQ](/blog/faq-mermaid-troubleshooting.md) -- solutions for rendering issues, syntax errors, and performance problems * [Create Mermaid Diagrams in Confluence](/blog/create-mermaid-diagrams-confluence.md) -- broader guide covering flowcharts, class diagrams, Gantt charts, and more Try Mermaid Plus for Confluence All 26 Mermaid diagram types with live preview and one-click templates — free for up to 10 users. [Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence) ## Related guides * [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md) * [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md) * [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md) * [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md) Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links) **Tags:** * [faq](/blog/tags/faq.md) * [mermaid](/blog/tags/mermaid.md) * [confluence](/blog/tags/confluence.md) * [sequence-diagram](/blog/tags/sequence-diagram.md) * [diagrams](/blog/tags/diagrams.md)