How to Render Mermaid Diagrams in Markdown

Visual documentation lands better when the figure lives in the same file as the prose. Mermaid lets you describe flowcharts, sequence diagrams, and more as text inside Markdown — then render them in preview, on GitHub, or in a PDF export.

This tutorial is the syntax-first companion to our PDF and print guides. Learn the fences here; then use render Mermaid diagrams to PDF when you need printable output.

Key Takeaways

• Use fenced blocks with the mermaid language tag.
• Start with flowchart, sequence, and Gantt — they cover most doc needs.
• Keep diagrams small enough to read in preview at 100% zoom.
• Validate in live preview before you share or export.

Table of Contents

• Mermaid Fence Basics
• Flowcharts
• Sequence Diagrams
• Gantt Charts
• State and Class Diagrams
• Preview and Export Next Steps
• Frequently Asked Questions

Mermaid Fence Basics

Create a fenced code block whose language tag is mermaid, then put diagram source inside — for example a left-to-right flowchart:

Rules:

• Language tag must be mermaid.
• One diagram per fence.
• Prefer short node IDs and readable labels.

Flowcharts

Top-down decision tree:

Left-to-right pipeline:

Deeper export guidance: render flowcharts from Markdown to PDF.

Sequence Diagrams

Limit participants so messages stay readable.

Gantt Charts

State and Class Diagrams

State:

Class (keep fields minimal for docs):

Preview and Export Next Steps

1. Paste into Markdown live preview — see Mermaid diagrams in Markdown preview.
2. Export with Mermaid to PDF when stakeholders need a file.
3. For stubborn print layout, read print Markdown with complex diagrams.
4. For full doc sets, follow technical documentation Markdown to PDF.

Frequently Asked Questions

Does GitHub render Mermaid in Markdown?

Yes on GitHub for many diagram types in README and docs files. Always confirm in the GitHub UI after push.

Can Mermaid diagrams go into PDF?

Yes when your converter supports Mermaid fences natively — MdReader does.

Why is my diagram showing as code?

The fence is missing the mermaid language tag, or the viewer does not run Mermaid.

Where should I learn PDF-specific layout rules?

Start with rendering Mermaid diagrams to PDF.

Practice Mermaid in Markdown, preview live, and export with MdReader when you need PDF.