Mermaid Sequence Diagram Markdown: GitHub and VS Code

Mermaid sequence diagram Markdown usually uses a fenced code block whose language identifier is mermaid. The diagram source remains reviewable text, while a compatible Markdown renderer turns it into an SVG or another visual representation. GitHub, GitLab, and current VS Code Markdown preview all document support for Mermaid fences, but they may not run the same Mermaid version.

This Mermaid sequence diagram Markdown guide shows the portable source format, platform-specific checks, and a troubleshooting path for diagrams that appear as raw code or fail after moving between documentation systems.

Use a Mermaid Sequence Diagram Markdown Fence

Mermaid sequence diagram Markdown starts by placing the diagram inside a fenced block and putting mermaid immediately after the opening fence:

```mermaid
sequenceDiagram
    actor User
    participant App
    participant API
    User->>App: Submit form
    App->>API: POST /requests
    API-->>App: 201 Created
    App-->>User: Show confirmation
```

A renderer that supports Mermaid displays this diagram:

sequenceDiagram
    actor User
    participant App
    participant API
    User->>App: Submit form
    App->>API: POST /requests
    API-->>App: 201 Created
    App-->>User: Show confirmation

Keep the Mermaid sequence diagram Markdown source in the file rather than committing only an exported image. The text can be reviewed with the surrounding documentation, and the image updates automatically when the source changes.

Mermaid Sequence Diagram Markdown on GitHub

GitHub's official diagram documentation says Mermaid sequence diagram Markdown fences render in Markdown files, issues, discussions, pull requests, and wikis. GitHub also renders committed .mermaid and .mmd files inside repositories.

Use the same fence shown above in a README or pull request description. Before merging:

1. Open the Preview tab or the rendered Markdown file.
2. Confirm GitHub's active Mermaid version supports every feature used by the source.
3. Keep a text explanation near the diagram when the visual communicates essential information.
4. Avoid assuming a third-party Markdown preview uses the same Mermaid build as GitHub.

GitHub documents a way to check the Mermaid version it currently uses. Mermaid sequence diagram Markdown with version-sensitive syntax should be tested in the actual GitHub preview instead of inferred from a local editor alone.

Mermaid Sequence Diagram Markdown on GitLab

GitLab's Markdown documentation supports Mermaid sequence diagram Markdown through a mermaid fenced block in comments, issues, merge requests, wiki pages, repository Markdown files, and other GitLab Flavored Markdown surfaces. Its current documentation states that GitLab supports Mermaid version 11.

The basic source is portable between GitHub and GitLab:

```mermaid
sequenceDiagram
    participant Pipeline
    participant TestJob
    participant DeployJob
    Pipeline->>TestJob: Run checks
    TestJob-->>Pipeline: Passed
    Pipeline->>DeployJob: Release application
    DeployJob-->>Pipeline: Deployment URL
```

Self-managed GitLab installations can differ in release version and security configuration. Validate Mermaid sequence diagram Markdown on the target instance, especially when the source relies on recently introduced Mermaid syntax or configuration.

Mermaid Sequence Diagram Markdown in VS Code

Current VS Code Markdown documentation says the built-in preview renders Mermaid sequence diagram Markdown fences and provides pan and zoom controls for larger diagrams. Open a side-by-side preview with the Markdown preview command and check the diagram before committing.

If a teammate uses an older VS Code release, the built-in preview may not include the same Mermaid integration. Update VS Code or use an explicitly chosen extension, then verify which Mermaid version that preview bundles. Mermaid sequence diagram Markdown can render differently in an extension and GitHub when their Mermaid versions do not match.

Keep Mermaid Sequence Diagram Markdown Portable

For Mermaid sequence diagram Markdown that must render on several hosts, design against the oldest Mermaid version in the delivery path.

Mermaid Sequence Diagram Markdown Compatibility Rules

Mermaid Sequence Diagram Markdown Validation Rules

OnUML currently uses Mermaid 11.17.2, so every Mermaid sequence diagram Markdown example in this series is tested against that runtime. A newer platform may support additional syntax, but adding it to a shared README can break an older documentation portal.

Mermaid Sequence Diagram Markdown README Template

A Mermaid sequence diagram Markdown section should tell readers what question the visual answers and what it intentionally omits.

## Create an order

The client sends one idempotent request. The API returns after the order and
outbox row are committed; fulfillment happens asynchronously.

```mermaid
sequenceDiagram
    autonumber
    actor Client
    participant API as Order API
    participant DB as Orders Database
    participant Queue as Event Queue

    Client->>API: POST /orders
    API->>DB: Insert order and outbox row
    DB-->>API: Commit confirmed
    API-->>Client: 201 Created
    API-)Queue: Publish OrderCreated
```

The diagram omits payment and fulfillment retries. See the linked runbook for
their policies and operational ownership.

The actual diagram source renders as follows:

sequenceDiagram
    autonumber
    actor Client
    participant API as Order API
    participant DB as Orders Database
    participant Queue as Event Queue

    Client->>API: POST /orders
    API->>DB: Insert order and outbox row
    DB-->>API: Commit confirmed
    API-->>Client: 201 Created
    API-)Queue: Publish OrderCreated

This Mermaid sequence diagram Markdown format gives reviewers both the interaction and the boundaries of the claim. A syntactically valid diagram can still be wrong if the implementation publishes before the commit or returns a different status.

Diagnose Raw Mermaid Sequence Diagram Markdown

When a page displays Mermaid sequence diagram Markdown as literal fenced source, work through these checks:

1. Confirm the opening fence is followed by mermaid, not diagram, sequence, or a misspelling.
2. Confirm the destination supports Mermaid; CommonMark itself does not require diagram rendering.
3. Make sure the fence is not nested inside another code block, list indentation, or unsupported HTML container.
4. Preview the file on the destination platform, not only in a local Markdown editor.
5. Check whether repository or instance policies disable scripts or diagram rendering.

Raw Mermaid sequence diagram Markdown usually means the host did not activate Mermaid. A Mermaid syntax error more often produces an error panel or an empty diagram after the host recognizes the fence.

Diagnose Mermaid Sequence Diagram Markdown Errors

If the host recognizes Mermaid sequence diagram Markdown but cannot render it, use this sequence:

1. Copy only the diagram source, without the Markdown fence, into the Mermaid Sequence Diagram Online Editor.
2. Confirm the first diagram line is sequenceDiagram.
3. Check that every alt, opt, loop, par, critical, break, rect, and box has a matching end.
4. Remove newer configuration or syntax, then restore one feature at a time.
5. Compare the Mermaid versions used by OnUML, the local preview, and the publishing platform.
6. Keep the simpler syntax when the document must remain portable across all three.

For complex Mermaid sequence diagram Markdown branching, use the Mermaid sequence diagram control-flow guide. For theme frontmatter and readability, use the styling guide, but remember that a destination may restrict author-provided configuration.

Review Mermaid Sequence Diagram Markdown Like Code

Treat Mermaid sequence diagram Markdown and its prose as one change:

• Update the interaction when an endpoint, event, or ownership boundary changes.
• Ask a reviewer to verify behavior, not just syntax.
• Keep participant names consistent across related documents.
• Test the happy path and the most important failure path.
• Remove stale diagrams instead of preserving a misleading visual.

For ready-to-adapt Mermaid sequence diagram Markdown patterns covering authentication, databases, queues, webhooks, and caches, continue with Mermaid Sequence Diagram Examples. Return to the Mermaid Sequence Diagram tutorial for core participant, arrow, activation, and note syntax.