Sequence Diagrams in GitHub and GitLab: Native Mermaid Support Explained

GitHub and GitLab both render Mermaid sequence diagrams natively in markdown. No plugins, no image files, no external hosting. Just write Mermaid code inside a mermaid code block and the diagram appears when the file is viewed. This is the single biggest reason engineering teams choose Mermaid over PlantUML for documentation that lives in Git.

Here is how to use it, the features that work (and the ones that do not), and a fast editing workflow with live preview.

How GitHub Renders Mermaid Sequence Diagrams

GitHub added native Mermaid support in February 2022. Since then, any markdown file that contains a mermaid-tagged code block renders the diagram when the file is viewed. This includes:

• README files at the root of a repository
• Documentation in /docs folders
• Markdown files anywhere in the repo
• Issue descriptions and comments
• Pull request descriptions and comments
• GitHub Discussions
• GitHub Wiki pages

The syntax: write a fenced code block with mermaid as the language identifier. Paste your Mermaid sequence diagram code. GitHub renders it when someone views the file.

The source code is still visible in raw file views and in git diffs, which is exactly what you want for version control. When the diagram changes, you can see the diff in a pull request the same way you see code changes. No binary files, no attachment management.

For Mermaid syntax that works in GitHub, see our complete syntax guide. Every feature documented there renders in GitHub.

GitLab Mermaid Support

GitLab added Mermaid rendering before GitHub did and has more mature support. The same syntax works: fenced code block with mermaid identifier.

GitLab Mermaid rendering works in:

• Repository markdown files (README, docs)
• Issue descriptions and comments
• Merge request descriptions and comments
• Epic descriptions
• Wiki pages
• Snippets

GitLab also supports Mermaid in self-hosted instances (Community Edition and Enterprise Edition). This is important for organizations running GitLab on-premises for compliance reasons. Your diagrams render in your self-hosted instance with no external service calls.

Additionally, GitLab has historical support for PlantUML via a server component. For teams already using PlantUML, this provides a migration path (use both Mermaid and PlantUML during transition). For new projects, Mermaid is simpler because it requires no server configuration.

Sell Custom Apparel — We Handle Printing & Free Shipping

Fast Editing Workflow: Browser Tool + Git

The problem with editing Mermaid directly in GitHub or GitLab: you cannot see the diagram while editing. You commit changes, wait for the page to render, discover the syntax error, commit a fix, wait again. This commit-cycle debugging is slow.

A faster workflow:

1. Open our sequence diagram tool in a browser tab
2. Edit your Mermaid code with live preview (renders on every keystroke)
3. Once the diagram looks right, copy the Mermaid source
4. Paste into your markdown file, commit, push
5. Verify the rendered version on GitHub or GitLab

The live preview catches syntax errors instantly. You never commit a broken diagram. The browser tool uses the same Mermaid library GitHub and GitLab use, so what you see in preview is exactly what renders after commit.

For VS Code users, the Mermaid Preview extension offers the same live preview inside the editor. See our VS Code guide for setup.

What Does Not Work in GitHub/GitLab Mermaid

Not every Mermaid feature renders identically in every context. Known limitations:

• Custom themes/colors: GitHub uses fixed light/dark themes. Custom theme directives in your Mermaid code may not apply as expected.
• Click handlers: Mermaid supports interactive links in some renderers. GitHub disables these for security reasons.
• Size constraints: Very large diagrams may be clipped or require scrolling. For complex systems, split into multiple smaller diagrams.
• Version differences: GitHub and GitLab may be on slightly different Mermaid versions. A feature added in the latest Mermaid release may not work immediately in GitHub. Check the Mermaid release notes if a feature seems broken.

For 95% of sequence diagram features (participants, arrows, loops, alt, opt, par, notes, activation bars), rendering is identical across GitHub, GitLab, VS Code, and our browser tool. You only hit the edge cases if you use advanced theming or interactive features.

The portability is worth the minor limitations. Your diagram source renders in at least 5-10 different platforms without modification. PlantUML, Lucidchart, and other alternatives require image exports or plugins to achieve the same reach.

For ER diagrams, flowcharts, and other diagram types that also render in GitHub/GitLab, see our ER diagram syntax guide and Mermaid flowchart guide.

Frequently Asked Questions

Does GitHub render Mermaid sequence diagrams?

Yes. GitHub has rendered Mermaid diagrams natively since February 2022. Write your diagram in a fenced code block with mermaid as the language identifier, and it renders automatically in README files, documentation, issues, pull requests, wikis, and discussions.

How do I add a sequence diagram to my GitHub README?

Open your README.md file. Add a fenced code block with the mermaid language tag. Paste your Mermaid sequence diagram code inside. Commit the file. When the README is viewed on GitHub, the diagram renders automatically. No image files or plugins needed.

Does GitLab support Mermaid diagrams?

Yes. GitLab has had native Mermaid support longer than GitHub. The same syntax works in repository markdown files, issues, merge requests, wiki pages, and snippets. Also works in self-hosted GitLab instances.

What is the difference between Mermaid in GitHub and in a browser tool?

The rendered output is essentially identical because both use the same Mermaid library. The browser tool adds live preview (you see the diagram as you type) which GitHub does not provide. Most developers edit in a browser tool or VS Code, then paste the finished Mermaid source into their GitHub markdown files.