Markdown Flow

Back to Blog

How to Add Mermaid Diagrams to Your Markdown Docs

A flowchart or sequence diagram usually means switching to a separate design tool, exporting an image, and pasting it into your document. Markdown Flow skips all of that - write a Mermaid diagram directly inside a fenced code block, and it renders live alongside the rest of your Markdown.

What Is Mermaid?

Mermaid is a diagramming syntax that turns plain text into flowcharts, sequence diagrams, and more. Instead of dragging boxes around in a design tool, you describe the relationship in text, and the diagram draws itself.

Drawing a Flowchart

Wrap the diagram description in a fenced code block labeled mermaid:

Drawing a Sequence Diagram

The same approach works for sequence diagrams, showing how messages pass between participants over time:

Diagrams That Match Your Theme

Mermaid diagrams automatically switch between a light and dark color scheme depending on which theme you're using in Markdown Flow, so they always stay readable against the background.

Exporting Diagrams

Diagrams render as part of your document across all three export formats - they appear in your PDF exactly as shown in the preview, and are included in your HTML export as fully rendered vector graphics.

Where Diagrams Come In Handy

  • Technical documentation that needs to show a process or architecture at a glance.
  • Explaining an algorithm or workflow an AI assistant walked you through step by step.
  • Onboarding docs that map out how a system or team process works.

Frequently Asked Questions

Do I need to install anything to use Mermaid? No - just write the diagram inside a fenced code block labeled mermaid and it renders automatically in the live preview.

What diagram types are supported? Flowcharts and sequence diagrams are the most common, along with other Mermaid diagram types like class diagrams and state diagrams.

Can ChatGPT write Mermaid syntax for me? Yes - ask an AI assistant to "draw this as a Mermaid flowchart" and paste the result directly into Markdown Flow.

Paste a process description into ChatGPT, ask for a Mermaid diagram, and drop the result into Markdown Flow to see it rendered instantly.