Mermaid Flowcharts in Markdown: A Practical Workflow

Choose the structure for your readers

Start with the process you want to explain. Give nodes stable identifiers and readable labels. TD lays out the process vertically; LR switches to a horizontal direction. Label decision branches with the actual conditions.

A small example to try

flowchart TD
  A[Draft] --> B{Reviewed?}
  B -->|No| A
  B -->|Yes| C[Publish]

Paste this example into the editor and compare the source with its preview. Change one element at a time so you can identify which syntax controls the result.

Check compatibility before sharing

Place Mermaid syntax inside a fenced code block with the mermaid language marker. The destination needs Mermaid support. If it shows code instead, that does not necessarily mean the syntax is invalid. Include a written explanation for accessibility and readers without diagram support.

A practical review checklist

1. Check headings and labels explain the content without extra context.
2. Test the example in the destination where people will read it.
3. Verify links and relative asset paths after moving the file.
4. Inspect exported documents separately from the live preview.
5. Keep the editable Markdown original alongside distributed copies.

Primary source and further reading

Read the specification or project documentation. Explore the complete Markdown guide and Compatibility Lab.

Want to inspect a small example? Try it in a Markdown preview, then verify your publishing destination.

All Markdown articles