- 1 1. What Is Mermaid?
- 2 2. Basic Usage of Mermaid
- 3 3. Creating Diagrams with Mermaid.js
- 4 4. How to Use Mermaid in WordPress
- 5 5. Best Practices for Using Mermaid
- 6 6. Summary
1. What Is Mermaid?
Overview and Key Features of Mermaid
Mermaid is a JavaScript library that lets you create diagrams and charts using text-based definitions. With this tool, you can generate visual diagrams easily just by writing code. Because it allows you to quickly create flowcharts, sequence diagrams, Gantt charts, and more, it is widely used by software developers, project managers, and many others.
One of Mermaid’s biggest strengths is that you can define diagrams using only code. This makes it easy to edit and manage diagrams without relying on a GUI. Mermaid is also integrated into platforms such as GitHub and Notion, giving it the flexibility to be used in many different situations.
Main Use Cases and Benefits of Mermaid
Use Cases
- Creating flowcharts and sequence diagrams for software development.
- Creating Gantt charts for project planning.
- Adding visual representations to Markdown files and Wiki documentation.
Benefits
- Simple syntax: You can write it like programming code, so even beginners can use it easily.
- Code-based management: You can manage versions using source control tools (e.g., Git).
- Fast creation and updates: Diagram changes are reflected immediately just by editing the code.
- Extensibility and customizability: You can customize the design with CSS and extend functionality with JavaScript.
2. Basic Usage of Mermaid
How to Install
Mermaid.js can be installed in two ways: using a CDN link or using npm.
1. Using a CDN Link
Add the following script tag to your HTML file.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</head>
<body>
<div class="mermaid">
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
</div>
</body>
</html>2. Using npm
If you have a Node.js environment ready, you can install it with the following command.
npm install mermaidWith this method, you can integrate Mermaid as part of a JavaScript project.
Basic Syntax and Grammar
With Mermaid.js, you can create diagrams using intuitive text-based syntax. Here are some common examples.
1. Flowchart
Below is an example of a flowchart definition.
graph TD;
A[Start] --> B[Process 1]
B --> C[Process 2]
C --> D[End]2. Sequence Diagram
A sequence diagram that shows a system workflow can be written like this.
sequenceDiagram
participant A as User
participant B as Server
A->>B: Send request
B-->>A: Return response3. Gantt Chart
A Gantt chart that is useful for project management can be written as follows.
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Planning
Task A :a1, 2024-01-01, 10d
Task B :a2, after a1, 7d
Task C :a3, after a2, 5dSupported Diagram Types
Mermaid.js supports the following types of diagrams and charts.
- Flowchart: Shows the flow of a process.
- Sequence diagram: Visualizes communication protocols and procedures.
- Gantt chart: Used for project management and scheduling.
- Class diagram: Used for object-oriented design.
- State diagram: Represents state transitions.
- Pie chart: Visualizes data proportions.
3. Creating Diagrams with Mermaid.js
How to Embed Mermaid in HTML
Mermaid.js can be easily embedded into HTML. Follow the steps below to create diagrams.
1. Basic HTML Structure
The following code shows a minimal example of using Mermaid.js in an HTML file.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Mermaid Diagram</title>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</head>
<body>
<h1>Flowchart Example</h1>
<div class="mermaid">
graph TD;
A[Start] --> B[Process 1]
B --> C[Process 2]
C --> D[End]
</div>
</body>
</html>2. Display Multiple Diagrams
If you want to display multiple diagrams, add multiple div tags in your HTML like this.
<div class="mermaid">
graph TD;
A --> B;
B --> C;
</div>
<div class="mermaid">
sequenceDiagram
participant A as User
participant B as Server
A->>B: Send request
B-->>A: Return response
</div>Initialization and Configuration with JavaScript
1. Initialization Settings
The following code initializes Mermaid.js programmatically.
mermaid.initialize({
startOnLoad: true,
theme: 'forest',
flowchart: { curve: 'basis' },
});With this configuration, the theme is changed to forest, and the flowchart lines are customized to use curved edges.
2. Add Diagrams Dynamically
The following example shows how to generate a diagram dynamically using JavaScript.
const code = `
graph LR;
X[Start] --> Y[Next step];
Y --> Z[End];
`;
const element = document.querySelector('#dynamicChart');
element.innerHTML = code;
mermaid.init(undefined, element);Practical Code Examples and Explanations
Example 1: Creating a Sequence Diagram
<div class="mermaid">
sequenceDiagram
participant User as User
participant Server as Server
User->>Server: Data request
Server-->>User: Data response
</div>Example 2: Creating a Gantt Chart
<div class="mermaid">
gantt
title Project Schedule
dateFormat YYYY-MM-DD
section Development Phase
Design :done, 2024-01-01, 2024-01-07
Implementation :active, 2024-01-08, 2024-01-20
Testing :2024-01-21, 2024-01-30
</div>4. How to Use Mermaid in WordPress
Plugin Introduction and Setup
If you want to use Mermaid.js in WordPress, the easiest way is to install a dedicated plugin. Here are some popular options.
1. Mermaid Plugin – “Mermaid Markdown Syntax Highlighting”
This plugin allows you to use Mermaid syntax directly inside your posts.
Installation Steps
- Log in to the WordPress admin dashboard.
- From the menu, click Plugins → Add New.
- In the search box, type Mermaid Markdown Syntax Highlighting.
- Install the plugin and activate it.
Configuration Steps
- After activation, you can adjust basic options from the settings screen.
- Customize settings such as the theme and auto-load on start.
How to Display Diagrams in a Post
After installing the plugin, you can display diagrams inside your post using shortcodes like the following.
Example: Insert a Flowchart
[mermaid]
graph TD;
A[Start] --> B[Process 1]
B --> C[Process 2]
C --> D[End]
[/mermaid]Example: Insert a Sequence Diagram
[mermaid]
sequenceDiagram
participant User
participant Server
User->>Server: Send request
Server-->>User: Return response
[/mermaid]Example: Insert a Gantt Chart
[mermaid]
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Development
Design :done, 2024-01-01, 2024-01-07
Implementation :active, 2024-01-08, 2024-01-20
Testing :2024-01-21, 2024-01-30
[/mermaid]Notes and Troubleshooting
1. What to Do If Diagrams Do Not Render
- Cause 1: The plugin is not activated correctly. → Re-check the plugin settings and make sure it is enabled.
- Cause 2: The Mermaid.js script is not being loaded. → It may be conflicting with your theme or other plugins, so disable plugins one by one to identify the conflict.
2. Manual Setup Without a Plugin
If you don’t want to use a plugin, you can also embed Mermaid.js manually by adding the following code to your theme’s functions.php.
function add_mermaid_script() {
echo '<script type="module">
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
mermaid.initialize({ startOnLoad: true });
</script>';
}
add_action('wp_footer', 'add_mermaid_script');
5. Best Practices for Using Mermaid
How to Manage Complex Diagrams
1. Split and Organize Your Code
When creating complex diagrams, keep your code organized by following these tips.
- Add comments for each section
%% Start of the flowchart
graph TD;
A[Start] --> B[Process 1]
%% Branching logic
B --> C[Process 2]
B --> D[Process 3]- Create templates and reuse them For large projects, preparing templates and maintaining consistency across multiple diagrams is important.
2. Manage Diagrams in External Files
Instead of embedding Mermaid code directly into an HTML or Markdown file, you can store it in external files. This improves maintainability.
Example: Save Mermaid code in a file named diagram.mmd and load it from HTML.
<div id="diagram-container"></div>
<script>
fetch('diagram.mmd')
.then(response => response.text())
.then((text) => {
const container = document.getElementById('diagram-container');
container.innerHTML = text;
mermaid.init(undefined, container);
});
</script>Customization and Theme Settings
1. Apply a Theme
Mermaid.js includes multiple built-in themes, allowing you to switch to a visually appealing style easily.
Theme List
- Default
- Dark
- Forest
- Neon
Configuration Example
mermaid.initialize({
theme: 'dark',
});2. Apply Custom CSS
If you want more detailed design adjustments, you can define styles with CSS.
.mermaid text {
font-family: Arial, sans-serif;
fill: #333;
}Performance Considerations
1. Adjust the Initialization Timing
Instead of initializing diagrams on page load, you can initialize Mermaid only when users need it. This reduces processing load.
const config = {
startOnLoad: false,
};
mermaid.initialize(config);
// Render only when needed
document.getElementById('render-btn').addEventListener('click', () => {
mermaid.init();
});2. Convert to Static Images
If performance is especially important, you can export Mermaid-generated diagrams as image files and use them as static images. This minimizes the load on the browser.
6. Summary
The Value and Convenience of Mermaid.js
Mermaid.js is a powerful JavaScript library that lets you create diagrams using code-based definitions. Since it can easily render many types of diagrams—such as flowcharts, sequence diagrams, and Gantt charts—it is an extremely useful tool for developers and project managers.
One of the biggest advantages of this library is that its simple syntax allows you to create complex diagrams efficiently. It can also integrate with CMS platforms like WordPress, making it an excellent way to present visual information in blog posts and technical documentation.
Review of Each Section
- What Mermaid is We explained the basic overview of Mermaid.js, its use cases, and the benefits of adopting it.
- Basic usage of Mermaid We introduced the fundamentals for practical use, from installation methods to basic syntax.
- Creating diagrams with Mermaid.js We provided detailed instructions on how to create diagrams using HTML and JavaScript.
- How to use Mermaid in WordPress We covered how to integrate Mermaid with WordPress, including plugin usage and real examples inside posts.
- Best practices for using Mermaid We offered practical advice on code management, performance optimization, and design customization.
Future Possibilities for Mermaid.js
Mermaid.js is an open-source project, and it may continue to add new features and supported formats in the future. It is also increasingly supported across many platforms such as GitHub, Notion, and WordPress, so its potential use cases are expected to expand even further.
Because it can be applied to many purposes—such as business documents, presentations, and enhancing project management tools—continuing to learn and practice Mermaid.js will help you use it even more effectively.
Final Notes
In this article, we covered Mermaid.js from the basics to practical usage. Since it is beginner-friendly and also useful for professional documentation, be sure to try using it.
When needed, refer back to this guide and start integrating Mermaid.js into your real projects and technical writing.
