GraphDraw – Flowcharts for Mermaid

Description

GraphDraw adds Mermaid diagrams to your WordPress posts and pages. You write a diagram as text, in Mermaid’s syntax, and the plugin draws it: flowcharts, sequence, class, state and Gantt diagrams, mind maps, timelines, Git graphs, architecture diagrams and every other type Mermaid has.

This makes it easy to include text-based diagrams in the block editor without additional tools or complex setups.

Playground Demo

Features:

• Add Mermaid diagrams with a dedicated block.
• Every diagram type of Mermaid 12, with starter code for flowcharts, sequence, class and state diagrams and mind maps.
• Real-time preview of diagrams in the editor, and the line of an error marked in the code.
• Optional controls for visitors: zoom for large diagrams, a fullscreen view, buttons to download a diagram as an SVG or PNG file, and a button that copies its code.
• Every Mermaid theme: one for the whole site under Settings → GraphDraw, and one per diagram where you need it. The automatic theme follows the page, dark mode included.
• Alignment (centre, wide and full width), spacing, and an optional caption.
• A title and a description of each diagram for screen readers.
• Optionally, a saved image of each diagram, for feeds and for browsers that run no JavaScript, which otherwise show its Mermaid code.
• A Mermaid Diagram widget for Elementor, with the block’s settings and a live preview.
• A [graphdraw] shortcode for the classic editor, page builders and text widgets.
• Optionally, Mermaid code that is already in your posts as code, such as a language-mermaid code block from a Markdown import, is shown as a diagram.
• Light on your pages: a page with a diagram loads one small script, then Mermaid when a diagram scrolls into view, and of Mermaid only the parts that diagram needs. A page without a diagram loads nothing.
• A choice of renderer: Mermaid.js, or Pele, which draws the same Mermaid code with less to download and faster.

Pele, a lighter renderer:

Under Settings → GraphDraw, Renderer sets what draws the diagrams of the whole site, in the editor and on your pages: Mermaid.js, the default, or Pele. Nothing in your posts changes, so you can switch back at any time.

Pele draws the same Mermaid code, every diagram type of the Mermaid version the plugin has, and loads much less: a page with a flowchart downloads 149 KB of JavaScript (62 KB compressed) where Mermaid.js takes 884 KB (242 KB compressed), and a diagram is drawn in a few milliseconds. In the editor it is 3 MB less. A page loads one renderer, never both.

Pele draws in a plain look of its own, so a diagram looks different from the same diagram in Mermaid.js:

• Themes count as light or dark. The theme settings offer Automatic, Light and Dark. Automatic follows the page, and turns dark with it without drawing the diagram again. A diagram that had another theme keeps it: Dark, Neo Dark, Redux Dark and Redux Dark Color are dark, and every other theme is light. A theme written in the code, in its front matter or in an %%{init}%% directive, counts the same way.
• Colours set in the code are ignored, such as themeVariables.
• Formulas between $$ are typeset with Temml, as MathML that the browser draws in its own math font. Temml is loaded only on a page whose diagrams have a formula. Mermaid.js keeps its own formulas, drawn by KaTeX.
• click with a JavaScript callback is dropped, as Mermaid.js does at its strict security level. Links (click A "https://…") work.
• A wide diagram is laid out for the width it has. On a narrow screen it may turn vertical below 640 pixels, and it is laid out again when its width changes, such as when a phone is turned. A download or a saved image has the full layout, whatever the screen.
• Zoom is Pele’s own. A diagram with the zoom control can be zoomed with a pinch, a double-click, Ctrl or ⌘ and the wheel, or by dragging, and with +, -, 0 and the arrow keys once it has focus.
• Labels are measured again once the site’s web font has loaded, so boxes fit the text in the font the page shows.
• A diagram that Pele can’t draw is shown as an error in the editor, and left as code on the page, as a syntax error is. Pele’s error message shows the line and a mark under the column.

Downloads, copying, fullscreen, saved images and the accessible title and description work with both renderers, and so does zoom. A download or a saved image of a Pele diagram has the colours of the diagram as you see it.

A developer can choose the renderer for a request, such as Pele only on some pages, with the graphdraw_renderer filter. It gets the site’s renderer, mermaid or pele, and returns one of them; anything else means Mermaid.js:

add_filter( 'graphdraw_renderer', function ( $renderer ) {
    return is_page( 'landing' ) ? 'pele' : $renderer;
} );

Pele’s options

A developer can set what Pele may do with the graphdraw_pele_options filter. It applies only when the renderer is Pele. People who write diagrams can’t set these options: the site decides what a diagram may do, such as showing links and images.

• links, images: true or false, to allow links and images in diagrams.
• linkSchemes, imageSchemes: lists of the URL schemes they may use, such as https. A list with anything but strings in it is ignored.
• linkRel: the rel of links.
• fontSize, padding, directionBreakpoint: positive numbers. directionBreakpoint is the width in pixels below which a wide diagram may turn vertical.
• autoDirection: true or false, to turn that off.
• limit, outputLimit, maxEdges: positive whole numbers, Pele’s limits.
• config: an array of Mermaid configuration used when a diagram sets none.

A key Pele doesn’t know, or a value of the wrong type, is ignored. The plugin sets the font, the measuring, the ids and the responsive layout itself, and they win over the filter:

add_filter( 'graphdraw_pele_options', function ( $options ) {
    $options['links']    = false;
    $options['fontSize'] = 15;
    return $options;
} );

Styling Pele diagrams with CSS

Pele draws with CSS variables, so a theme can restyle its diagrams. CSS written for Mermaid.js’s SVG doesn’t apply to Pele’s, which has other elements and classes.

• Colours: --pele-bg, --pele-fg, --pele-muted, --pele-line, --pele-surface, --pele-surface-alt, --pele-border, --pele-accent, --pele-critical, --pele-error, and --pele-series-1 to --pele-series-8 for charts.
• Fonts: --pele-font for labels and --pele-font-mono for monospace labels.
• Weights and corners: --pele-title-weight, --pele-heading-weight, --pele-bold-weight and --pele-radius.
• Classes: .pele on the SVG, and .pele-node, .pele-edge, .pele-edge-label, .pele-cluster, .pele-cluster-label, .pele-label, .pele-title, .pele-marker, .pele-icon and .pele-math on its parts. A node also has a data-id, its id in the code, so [data-id="start"] picks one node. Pele’s page about theming lists them all.

The plugin puts the light or dark palette on the diagram’s canvas, .graphdraw-diagram__canvas, as inline variables, which beat a rule on the canvas or on an element above it. To change a colour, set the variable on the SVG inside it:

.graphdraw-diagram__canvas > svg {
    --pele-accent: #c2410c;
    --pele-radius: 8px;
}

Fonts are different: labels are measured in the font before they are drawn. The plugin reads --pele-font and --pele-font-mono on the diagram, .graphdraw-diagram, or else uses the diagram’s own font, and writes the font it measured in into the SVG. So set them on .graphdraw-diagram, not on the SVG. A download takes the values the diagram has on the page, so your CSS counts in it too.

Icons:

A developer can register icon packs with the graphdraw_icon_packs filter, for diagrams drawn by either renderer. A pack is the URL of an Iconify JSON file, by the name diagrams use before the colon:

add_filter( 'graphdraw_icon_packs', function ( $packs ) {
    $packs['fa']    = 'https://cdn.jsdelivr.net/npm/@iconify-json/fa6-solid@1.2.4/icons.json';
    $packs['logos'] = 'https://cdn.jsdelivr.net/npm/@iconify-json/logos@1.2.17/icons.json';
    return $packs;
} );

Then a diagram can use fa:fa-car in a label, an icon shape such as A@{ icon: "fa:user" }, and (logos:aws) in an architecture diagram. A pack’s name has lower-case letters, digits and hyphens. A pack is fetched only on a page whose diagrams use one of its icons. Icons are drawn as shapes only: scripts, event handlers and outside links in a pack’s markup are removed before it reaches the page. People who write diagrams can’t add packs.

Shortcode:

Where the block can’t be used, write the diagram between [graphdraw] and [/graphdraw]:

[graphdraw caption="Checkout" zoom download]
flowchart LR
A[Cart] --> B{Paid?}
B -->|Yes| C[Done]
[/graphdraw]

Its attributes are the settings of the block:

• theme: a Mermaid theme, such as forest or dark. Without one, the theme set for the site.
• caption: a caption under the diagram.
• zoom and download: zoom controls and download buttons for visitors. Write them without a value, or as zoom="1".
• title and description: what screen readers read for the diagram.
• align: center, wide or full.

Mermaid code in posts:

Content that came from Markdown often holds its diagrams as code. Switch on “Show code marked as Mermaid as diagrams” under Settings → GraphDraw, and visitors see that code as diagrams, without anyone converting it:

• a Code block with the additional CSS class language-mermaid (under Advanced, in the settings of the block),
• a <pre> element with that class, or whose <code> element has it, as in <pre><code class="language-mermaid">.

The post and the editor keep the code. These diagrams have the theme set for the site, and no controls. To give one its own settings, select the Code block and transform it into a Mermaid Diagram block.

Abilities for AI agents:

On WordPress 6.9 and later, the plugin registers abilities with the WordPress Abilities API, in the “Mermaid diagrams” category. AI agents and automation can use them to work with diagrams, for example through the MCP Adapter or the REST API under wp-abilities/v1:

• graphdraw/list-diagram-types: the diagram types with starter code.
• graphdraw/list-diagrams: the diagrams in one post, or in every post that has some.
• graphdraw/get-diagram: one diagram of a post.
• graphdraw/build-block-markup: the block markup of a diagram, for other abilities that write posts.
• graphdraw/insert-diagram: adds a diagram to a post.
• graphdraw/update-diagram: changes the code or the settings of a diagram.
• graphdraw/delete-diagram: removes a diagram from a post.
• graphdraw/validate-diagram: parses a diagram in the block editor and reports its errors (WordPress 7.0 and later). The server can’t parse Mermaid, so the other abilities don’t validate code.

A diagram is addressed by the ID of its post and its index among the post’s diagrams. Changes need the hash a read returned, so a diagram edited in the meantime is never overwritten, and every change leaves a revision. Each ability is open only to those who could make the same change in the editor: users work with the diagrams of the posts they can edit.

Saved images:

A diagram is drawn in the visitor’s browser, so a feed reader, or a browser that runs no JavaScript, shows its Mermaid code instead. Switch on “Save an image of each diagram” under Settings → GraphDraw to give those readers a picture:

• The block editor makes a PNG image of each diagram of a post when the post is opened or saved in it. A post written before gets its images the next time it is opened in the editor.
• Feeds show the image in place of the code. On the site the image is in a <noscript> element, so browsers that run JavaScript never load it, and show the live diagram as before.
• An image is of one version of a diagram. When the code or the theme of a diagram is changed anywhere else, through the abilities for example, its image is removed, and those readers see the code again until the post is opened in the editor.
• The text of the image, for those who can’t see it, is the description of the diagram, or else its title.
• The images are files in wp-content/uploads/graphdraw/. They are deleted with their post, and with the plugin.

The diagrams of synced patterns, template parts, widgets and shortcodes get no image.

Libraries:

The diagrams are drawn by Mermaid, by the Mermaid project (MIT licence), or by Pele, by Obsidian (MIT licence). With Pele, formulas are typeset by Temml, by Ron Kok (MIT licence). For a diagram that asks for the ELK layout, Mermaid uses ELK, by the Eclipse Foundation, as elkjs (Eclipse Public License 2.0, which allows the GPL as a secondary licence). All four are included in the plugin. GraphDraw is an independent plugin, not affiliated with or endorsed by the Mermaid project. Mermaid’s files also include the libraries Mermaid is built with, such as KaTeX, DOMPurify, D3, dagre and Cytoscape.js, under the MIT, ISC, Apache 2.0 and similar licences.

Source code:

The JavaScript in the plugin’s build/ folder is compiled. Its source, with the build scripts, is on GitHub: land0r/graphdraw. Run npm ci && composer install && npm run build there to build it.

External services

GraphDraw connects to no outside service by itself: Mermaid, Pele and Temml are included in the plugin, and nothing is sent anywhere.

Icon packs are the one exception, and only when a site adds them. A pack registered with the graphdraw_icon_packs filter is downloaded by the visitor’s browser from the URL the site gave, only on a page whose diagrams use one of its icons. The request is a plain download of the pack’s JSON file: no data about the site or the visitor is sent with it, beyond what any browser request carries, such as the IP address and the user agent. The example in “Icons” above uses jsDelivr: terms of use and privacy policy.