Mermaid lets you write diagrams as plain text, a few lines of simple syntax, and have them render as clean flowcharts, sequence diagrams, or Gantt charts. In WordPress you get that with a small plugin, so you can build and edit diagrams right inside a post instead of designing images by hand.
Here is how to set it up in the block editor, the classic editor, and page builders, with a live example, plus an honest note on when a plugin is the right call and when a static image is simpler.
Key Takeaways
- Mermaid turns plain-text syntax into diagrams, so you edit a flowchart by editing text, not redrawing an image.
- The WP Mermaid plugin adds the support; then you paste Mermaid code into a Code block, a
[mermaid]shortcode, or a Shortcode block. - Diagrams render in the browser from your text, which keeps them editable but adds a small script load on those pages.
- For a one-off diagram you rarely change, exporting a static image from the Mermaid Live Editor avoids adding a plugin at all.
What Mermaid is, and why use it in WordPress
Mermaid is a diagramming tool that reads a markdown-like syntax and draws the diagram for you. Instead of dragging boxes around in a design tool, you describe the structure in text (for example, A points to B, B points to C) and Mermaid lays it out. It supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more.
The reason it is worth using inside WordPress is editability. A diagram saved as an image is frozen; changing one step means reopening a design tool and re-exporting. A Mermaid diagram is just text in your post, so updating it is as quick as editing a sentence, which matters a lot for things like process flows or content structures that change over time.
How to add a Mermaid diagram in WordPress, step by step
Step 1: Install the WP Mermaid plugin
WordPress does not render Mermaid on its own, so you need a plugin that loads the Mermaid library and handles the markup. From your dashboard, go to Plugins > Add New, search for WP Mermaid, then install and activate it. Once active, it allows Mermaid syntax in your posts and pages.
Step 2: Write your diagram in Mermaid syntax
Mermaid syntax is short and readable. Here is a basic flowchart that maps a main topic down to its parts:
graph TD
A[Fitness] --> B[Strength Training]
A --> C[Cardio]
A --> D[Nutrition]
B --> E[Weightlifting]
C --> F[Running]
D --> G[Meal Planning]The first line sets the diagram type and direction (graph TD means a top-down flowchart), and each arrow line draws a connection. You can swap TD for LR to lay it left-to-right, and the same idea extends to sequence and Gantt charts; the full Mermaid documentation has the syntax for each type.
Step 3: Add it in the block editor (Gutenberg)
In the block editor, click the + to add a new block, choose the Code block, and paste your Mermaid syntax into it. WP Mermaid picks up the code block and renders the diagram on the front end, so what looks like plain text in the editor becomes a drawn chart on the live page.
Step 4: Add it in the classic editor or a page builder
If you are on the classic editor or a page builder, use the shortcode instead. Wrap your Mermaid code in the shortcode tags and the plugin will render it the same way:
[mermaid] graph TD; A[Start] --> B[End]; [/mermaid]In a page builder, drop in a Shortcode element (or a shortcode widget) and paste the same thing. This is also the route to use on any WordPress version below 5.0, where the block editor is not available.
What that diagram looks like
Here is the flowchart from Step 2, drawn out so you can see how the text maps to the shape:
Diagrams like this are handy for showing structure visually, which is exactly why they fit content-planning work such as a topical map for SEO, where a pillar topic branches into clusters.
Plugin or static image: which should you use?
The one trade-off worth knowing is that Mermaid renders client-side, in the visitor’s browser, so any page with a diagram loads the Mermaid script to draw it. On a handful of pages that is nothing to worry about, but it is a real consideration if you are very strict about script load.
That gives a simple rule of thumb. If you publish diagrams often and want them editable, the plugin is clearly the right tool. If you just need a single diagram you will rarely touch, you can build it in the free Mermaid Live Editor, export it as an SVG or PNG, and place that image, no plugin required. Both are valid; pick by how often the diagram will change.
So, is the Mermaid plugin the right way to add diagrams?
If this were my site, I would install WP Mermaid the moment I knew I would be making diagrams regularly, because keeping them as editable text saves real time over redrawing images. The small client-side render cost is a fair price for that flexibility on a normal content site.
The only time I would skip it is a true one-off: a single chart I will never edit, where exporting a static image keeps the site that bit leaner. For everything else, the plugin is the cleaner long-term choice.
Update Logs
28 Jun 2026
- Refreshed the walkthrough with clearer block and shortcode steps, a cleaner rendered example, and guidance on when to use the plugin versus a static exported image.
Want our posts to show up more often on Google?
One step & Google will surface this site in your Top Stories.
