Mermaid diagrams and flowcharts have been gaining traction, especially with GitHub’s announcement that they are natively supported in Markdown. Let’s take a look at what they are, how to use them, and just as importantly: why.
Just like you might want to embed your CodePen demo directly in your documentation source, having your diagrams and charts live adjacent to your text helps prevent them from rotting — that is, drifting out of sync with the state of your document. Just as unhelpful, obsolete, or otherwise misleading comments in your code can be objectively worse than no comments, the same goes for diagrams.
Mermaid diagrams pair well with Jamstack and static site generators, which continue to grow in popularity. The pairing is natural. While Mermaid diagrams aren’t Markdown-exclusive, they are Markdown-inspired. Using the same markup abstractions Markdown provides to notate code, Mermaid can be represented the same to output diagrams and flowcharts. And Markdown is to Jamstack and static sites as peanut butter is to jelly.
If your site is authored in Markdown, processed into HTML, and you have enough control to add a bit of custom JavaScript, then you can use the ideas we’re covering in this article to fit your own needs and implement diagrams with Mermaid conveniently alongside the rest of your Markdown. Is “diagrams-as-code” a term yet? It should be.
For example, let’s say you’re working on a fancy new product and you want to provide a roadmap in the form of a Gantt chart (or some other type — say flowcharts, sequences, and class diagrams). With Mermaid, you can do this in a small handful of lines:
gantt title My Product Roadmap dateFormat YYYY-MM-DD section Cool Feature A task :a1, 2022-02-25, 30d Another task :after a1, 20d section Rad Feature Task in sequence :2022-03-04, 12d Task, No. 2 :24d
Which will render a nice SVG diagram like so:
Pro tip: Mermaid has a live editor which lets you try it out without the commitment over at mermaid.live.
Mermaid diagrams in Markdown
Mermaid goes well with Markdown because it presents itself as just another fenced code block, only using the mermaid language syntax set. For example, this block of code:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
…produces an HTML
element with the code block contents inside:
<pre rel="HTML" data-line=""><pre class="brush:php;toolbar:false"><code>graph TD;
A-->B;
A-->C;
B-->D;
C-->D;</code>
If you’re using a Markdown processor aligned with the CommonMark spec, it’ll more resemble this:
<pre class="brush:php;toolbar:false"><code>graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
</code>
View demo
The Mermaid API’s default behavior expects a
or <span> (like from a syntax highlighter) that you might see in the conversion from Markdown-to-HTML.
<h3 id="Finessing-with-JavaScript">Finessing with JavaScript</h3>
<p>With a bit of JavaScript, it’s reasonable to take the Markdown-generated HTML and finesse it into the </p>
<div> tag that Mermaid targets. It’s worth noting that $element.textContent is purposeful here: Markdown will HTML-encode specific characters (like > into >) that Mermaid uses. It also filters out any erroneous HTML elements that are descendants of the <pre class="brush:php;toolbar:false"> element.
<pre rel="JavaScript" data-line="">// select <pre class="brush:php;toolbar:false"> _and_ <pre class="brush:php;toolbar:false"><code>
document.querySelectorAll("pre.mermaid, pre>code.language-mermaid").forEach($el => {
// if the second selector got a hit, reference the parent <pre class="brush:php;toolbar:false">
if ($el.tagName === "CODE")
$el = $el.parentElement
// put the Mermaid contents in the expected <div>
// plus keep the original contents in a nice <details>
$el.outerHTML = `
<div>${$el.textContent}</div>
<details>
<summary>Diagram source</summary>
<pre class="brush:php;toolbar:false">${$el.textContent}</pre>
</details>
`
})
<p>Now that our HTML is properly-formatted, let’s implement Mermaid to do the rendering.</p>
<h3 id="Using-Mermaid">Using Mermaid</h3>
<p>Mermaid is published as an npm package, so you can grab a copy by using a package-aware CDN, like unpkg. You’ll want to use the minified code (e.g., mermaid.min.js) instead of the default export of mermaid.core.js. For example:</p>
<pre rel="HTML" data-line=""><script src="https://unpkg.com/%5Bemail%C2%A0protected%5D/dist/mermaid.min.js"></script></pre>
<p>Mermaid is <em>also</em> ESM-ready, so you can use Skypack to load it up as well:</p>
<pre rel="HTML" data-line=""><script type="module">
import mermaid from "https://cdn.skypack.dev/[email&#160;protected]";
</script></pre>
<p>You could stop right here if you want to keep things simple. By default, Mermaid will auto-initialize itself when the document is ready. As long as you do the Markdown-to-HTML finessing with JavaScript mentioned earlier — <em>before</em> loading in Mermaid — you’ll be all set.</p>
<p>However, Mermaid has a couple settings worth configuring:</p>
<pre rel="JavaScript" data-line="">// initialize Mermaid to [1] log errors, [2] have loose security for first-party
// authored diagrams, and [3] respect a preferred dark color scheme
mermaid.initialize({
logLevel: "error", // [1]
securityLevel: "loose", // [2]
theme: (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) ?
"dark" :
"default" // [3]
})</pre>
<ol>
<li>logLevel will give you a bit more visibility into any errors that may arise. If you want to see more information, you can choose a more verbose level (or vice versa).</li>
<li>securityLevel relates to the level of trust for the diagram source. If it’s content that <em>you</em> are authoring, then "loose" is fine. If it’s user-generated content, it’s probably best leaving the "strict" default in place.</li>
<li>theme changes the styling of the rendered diagrams. By querying the preferred color scheme and leveraging a ternary operator, we can specify "dark" as appropriate.</li>
</ol>
<h3 id="All-together-now">All together now!</h3>
<p>Here are a couple of Mermaid diagrams examples in Markdown:</p>
<h3 id="Deeper-waters">Deeper waters</h3>
<p>This strategy is particularly effective because it’s <em>progressive</em>: if JavaScript is disabled then the original Mermaid source is displayed as-is. No foul.</p>
<p>There’s also a fully-fledged command line interface for Mermaid which, if you’re interesting in exploring, could potentially be leveraged to display diagrams that are completely server-side rendered. Between the Mermaid CLI and the online generator, it may even be possible to hook into whatever build process you use to generate a snapshot of a diagram and display it as an <img alt="Making Mermaid Diagrams in Markdown" > fallback instead of the source code.</p>
<p>Hopefully, we’ll see more native Mermaid integrations like this as Mermaid continues to grow in popularity. The usefulness of having visual charts and diagrams alongside documentation is unquestionable — from product roadmaps to decision trees and everything in between. That’s the sort of information that’s just plain difficult to document with words alone.</p>
<p>Mermaid charts solve that, and in a way that ensures the information can be managed and maintained alongside the rest of the documentation.</p></details>
</div></pre>
The above is the detailed content of Making Mermaid Diagrams in Markdown. For more information, please follow other related articles on the PHP Chinese website!
Hot AI Tools
Undress AI Tool
Undress images for free
Undresser.AI Undress
AI-powered app for creating realistic nude photos
AI Clothes Remover
Online AI tool for removing clothes from photos.
Clothoff.io
AI clothes remover
Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!
Hot Article
Hot Tools
Notepad++7.3.1
Easy-to-use and free code editor
SublimeText3 Chinese version
Chinese version, very easy to use
Zend Studio 13.0.1
Powerful PHP integrated development environment
Dreamweaver CS6
Visual web development tools
SublimeText3 Mac version
God-level code editing software (SublimeText3)
CSS tutorial for creating loading spinners and animations
Jul 07, 2025 am 12:07 AM
There are three ways to create a CSS loading rotator: 1. Use the basic rotator of borders to achieve simple animation through HTML and CSS; 2. Use a custom rotator of multiple points to achieve the jump effect through different delay times; 3. Add a rotator in the button and switch classes through JavaScript to display the loading status. Each approach emphasizes the importance of design details such as color, size, accessibility and performance optimization to enhance the user experience.
Addressing CSS Browser Compatibility issues and prefixes
Jul 07, 2025 am 01:44 AM
To deal with CSS browser compatibility and prefix issues, you need to understand the differences in browser support and use vendor prefixes reasonably. 1. Understand common problems such as Flexbox and Grid support, position:sticky invalid, and animation performance is different; 2. Check CanIuse confirmation feature support status; 3. Correctly use -webkit-, -moz-, -ms-, -o- and other manufacturer prefixes; 4. It is recommended to use Autoprefixer to automatically add prefixes; 5. Install PostCSS and configure browserslist to specify the target browser; 6. Automatically handle compatibility during construction; 7. Modernizr detection features can be used for old projects; 8. No need to pursue consistency of all browsers,
What is the difference between display: inline, display: block, and display: inline-block?
Jul 11, 2025 am 03:25 AM
Themaindifferencesbetweendisplay:inline,block,andinline-blockinHTML/CSSarelayoutbehavior,spaceusage,andstylingcontrol.1.Inlineelementsflowwithtext,don’tstartonnewlines,ignorewidth/height,andonlyapplyhorizontalpadding/margins—idealforinlinetextstyling
Styling visited links differently with CSS
Jul 11, 2025 am 03:26 AM
Setting the style of links you have visited can improve the user experience, especially in content-intensive websites to help users navigate better. 1. Use CSS's: visited pseudo-class to define the style of the visited link, such as color changes; 2. Note that the browser only allows modification of some attributes due to privacy restrictions; 3. The color selection should be coordinated with the overall style to avoid abruptness; 4. The mobile terminal may not display this effect, and it is recommended to combine it with other visual prompts such as icon auxiliary logos.
Creating custom shapes with css clip-path
Jul 09, 2025 am 01:29 AM
Use the clip-path attribute of CSS to crop elements into custom shapes, such as triangles, circular notches, polygons, etc., without relying on pictures or SVGs. Its advantages include: 1. Supports a variety of basic shapes such as circle, ellipse, polygon, etc.; 2. Responsive adjustment and adaptable to mobile terminals; 3. Easy to animation, and can be combined with hover or JavaScript to achieve dynamic effects; 4. It does not affect the layout flow, and only crops the display area. Common usages are such as circular clip-path:circle (50pxatcenter) and triangle clip-path:polygon (50%0%, 100 0%, 0 0%). Notice
How to create responsive images using CSS?
Jul 15, 2025 am 01:10 AM
To create responsive images using CSS, it can be mainly achieved through the following methods: 1. Use max-width:100% and height:auto to allow the image to adapt to the container width while maintaining the proportion; 2. Use HTML's srcset and sizes attributes to intelligently load the image sources adapted to different screens; 3. Use object-fit and object-position to control image cropping and focus display. Together, these methods ensure that the images are presented clearly and beautifully on different devices.
Demystifying CSS Units: px, em, rem, vw, vh comparisons
Jul 08, 2025 am 02:16 AM
The choice of CSS units depends on design requirements and responsive requirements. 1.px is used for fixed size, suitable for precise control but lack of elasticity; 2.em is a relative unit, which is easily caused by the influence of the parent element, while rem is more stable based on the root element and is suitable for global scaling; 3.vw/vh is based on the viewport size, suitable for responsive design, but attention should be paid to the performance under extreme screens; 4. When choosing, it should be determined based on whether responsive adjustments, element hierarchy relationships and viewport dependence. Reasonable use can improve layout flexibility and maintenance.
What are common CSS browser inconsistencies?
Jul 26, 2025 am 07:04 AM
Different browsers have differences in CSS parsing, resulting in inconsistent display effects, mainly including the default style difference, box model calculation method, Flexbox and Grid layout support level, and inconsistent behavior of certain CSS attributes. 1. The default style processing is inconsistent. The solution is to use CSSReset or Normalize.css to unify the initial style; 2. The box model calculation method of the old version of IE is different. It is recommended to use box-sizing:border-box in a unified manner; 3. Flexbox and Grid perform differently in edge cases or in old versions. More tests and use Autoprefixer; 4. Some CSS attribute behaviors are inconsistent. CanIuse must be consulted and downgraded.
