Mermaid là một công cụ cho phép tạo sơ đồ và biểu đồ bằng văn bản. Thay vì vẽ bằng công cụ đồ họa, bạn chỉ cần viết một đoạn script đơn giản và Mermaid sẽ tự động tạo ra diagram.
Mermaid thường được sử dụng trong:
  • Documentation kỹ thuật
  • Architecture diagram
  • Flowchart quy trình
  • Sequence diagram
  • ER diagram
Tuy nhiên, Markdown của EzyPlatform không tự động render Mermaid thành diagram HTML. Vì vậy chúng ta cần thêm một bước xử lý bằng JavaScript.
Bài viết này hướng dẫn cách hiển thị Mermaid diagram khi viết Markdown trên EzyPlatform.

Viết Mermaid trong Markdown

Để viết Mermaid trong Markdown, bạn chỉ cần tạo một code block với ngôn ngữ là mermaid.
Ví dụ:
```mermaid
flowchart TD
    A[Start] --> B{Is Markdown Table?}
    B -- Yes --> C[Convert to HTML]
    B -- No --> D[Keep Original Text]
    C --> E[Return Result]
    D --> E[Return Result]
```
Mermaid script:
flowchart TD
    A[Start] --> B{Is Markdown Table?}
    B -- Yes --> C[Convert to HTML]
    B -- No --> D[Keep Original Text]
    C --> E[Return Result]
    D --> E[Return Result]
Trong các hệ thống hỗ trợ Mermaid trực tiếp, sơ đồ sẽ được render ngay lập tức.

Cách EzyPlatform xử lý Mermaid Markdown

Trong EzyPlatform, Markdown engine không convert Mermaid sang HTML diagram.
Thay vào đó, nó chỉ chuyển code block thành HTML dạng:
<div class="source-mermaid">
    <pre>
flowchart TD
    A[Start] --> B{Is Markdown Table?}
    B -- Yes --> C[Convert to HTML]
    B -- No --> D[Keep Original Text]
    C --> E[Return Result]
    D --> E[Return Result]
    </pre>
</div>
Tức là Mermaid chỉ được hiển thị dưới dạng code, chưa phải là diagram.
Để hiển thị diagram, bạn cần:
  1. Include thư viện Mermaid
  2. Dùng JavaScript để render các block .source-mermaid

Include thư viện Mermaid

Bạn cần thêm thư viện Mermaid chính thức vào trang.
<script src="https://cdn.jsdelivr.net/npm/mermaid@11.12.2/dist/mermaid.min.js"
        integrity="sha256-0IMKbAVUbp7bj+IKj1RfPg3HxMMTTVhLrZwTqZ16ceA="
        crossorigin="anonymous">
</script>
Thư viện này sẽ giúp chuyển Mermaid script thành SVG diagram.

Render Mermaid bằng JavaScript thuần

Sau khi load thư viện Mermaid, bạn cần viết một đoạn JavaScript để:
  • tìm các block .source-mermaid
  • lấy nội dung script
  • render diagram
Ví dụ: 
<script>
    mermaid.initialize({
        startOnLoad: false,
        theme: "default"
    });

    document.querySelectorAll('.source-mermaid pre').forEach((pre, index) => {
        const code = pre.textContent.trim();

        if (!code) {
            return;
        }

        const container = document.createElement('div');
        const id = 'mermaid-diagram-' + index;

        container.className = 'mermaid';
        container.id = id;
        container.textContent = code;

        pre.parentElement.replaceWith(container);

        mermaid.render(id + '-svg', code)
            .then(({ svg }) => {
                container.innerHTML = svg;
            })
            .catch(err => {
                console.error('Mermaid render error:', err);
            });
    });
</script>

Cách hoạt động

Đoạn script trên thực hiện các bước:
  1. Khởi tạo Mermaid engine
  2. Tìm tất cả các block .source-mermaid pre
  3. Lấy nội dung Mermaid script
  4. Tạo container mới để chứa diagram
  5. Gọi mermaid.render() để tạo SVG
  6. Chèn SVG vào trang web

Render Mermaid bằng jQuery

Nếu dự án của bạn đang dùng jQuery, có thể viết code ngắn gọn hơn.
mermaid.initialize({
    startOnLoad: false,
    theme: "default"
});
    
$('.source-mermaid pre').each(function (index) {
    var preElement = $(this);
    var code = $.trim(preElement.text());

    if (!code) {
        return;
    }

    var id = 'mermaid-diagram-' + index;

    var $container = $('<div>', {
        class: 'mermaid',
        id: id,
        text: code
    });

    preElement.parent().replaceWith($container);

    mermaid
        .render(id + '-svg', code)
        .then(function (result) {
            $container.html(result.svg);
        })
        .catch(function (err) {
            console.error('Mermaid render error:', err);
        });
});
Logic xử lý vẫn giống phiên bản JavaScript thuần, chỉ khác là sử dụng jQuery để thao tác DOM.

Best Practices khi sử dụng Mermaid

Khi sử dụng Mermaid trong EzyPlatform, bạn nên lưu ý:
  • Luôn viết diagram trong code block mermaid
  • Đảm bảo thư viện Mermaid đã được load trên trang
  • Render diagram sau khi nội dung Markdown đã được render
  • Bắt lỗi khi Mermaid render thất bại để dễ debug

Tổng kết

Mặc dù Markdown của EzyPlatform không tự động render Mermaid diagram, nhưng bạn hoàn toàn có thể hỗ trợ Mermaid bằng cách:
  1. Viết Mermaid script trong Markdown
  2. Include thư viện Mermaid
  3. Render các block .source-mermaid bằng JavaScript
Cách này cho phép bạn sử dụng Mermaid để tạo:
  • Flowchart
  • Architecture diagram
  • Workflow diagram
  • Technical documentation
một cách dễ dàng trong hệ sinh thái EzyPlatform.