How GitLab renders Mermaid
GitLab renders Mermaid from fenced code blocks with the mermaid language tag in markdown files, issues, merge requests, and wikis.
Like GitHub, GitLab pins its own Mermaid version and upgrades it with GitLab releases. Self-managed GitLab instances can run considerably older versions than GitLab.com, so a diagram that renders on GitLab.com may still fail for teams on a self-hosted instance.
```mermaid
sequenceDiagram
Dev->>GitLab: Push markdown with Mermaid
GitLab-->>Dev: Rendered diagram in MR
```Size and performance guards
GitLab enforces limits on Mermaid blocks to protect page performance: overly large sources or diagrams with very many nodes and edges may be truncated, refuse to render, or require an explicit click before rendering.
If a diagram silently fails on GitLab but renders elsewhere, size is the first thing to check. Splitting one big diagram into several small ones is the most reliable fix.
What commonly breaks
Newer or beta diagram types depend on the instance's deployed Mermaid version — verify before relying on them, especially on self-managed instances.
Interactive click directives are not available.
Custom init and theme directives may conflict with GitLab's styling, particularly in dark mode.
The same parser traps apply as everywhere: a lowercase 'end' in flowchart labels, unquoted special characters in labels, and stray tabs can all break parsing.
Safe authoring workflow
Draft the diagram in the MermaidPen studio with the GitLab-safe preset, which favors long-stable syntax and flags risky constructs.
Keep individual diagrams small; use several focused diagrams rather than one map of everything.
For documentation that must never break (runbooks, onboarding docs), export SVG from the studio and commit the image alongside the Mermaid source.