blog.dopana

Quay lại

Bạn chèn một vài sơ đồ kiến trúc vào bài viết blog bằng cú pháp ````mermaid`. Khi bạn đọc mở trang, nội dung bài viết hiện lên trước, nhưng vị trí sơ đồ thì trống trơn hoặc chỉ là đoạn mã thô. Vài giây sau, khi trình duyệt tải xong gói thư viện nặng hàng Megabyte, trang web mới giật mạnh một cái (Layout Shift) để vẽ biểu đồ ra màn hình.

Đó chính là trải nghiệm phổ biến khi dùng các thư viện render Mermaid phía client như astro-mermaid. Bài viết này sẽ hướng dẫn cách thay thế hoàn toàn astro-mermaid bằng Pele — một bộ render Mermaid siêu nhẹ giúp chuyển hóa cú pháp sơ đồ thành SVG thuần ngay tại thời điểm build (SSG), cắt giảm 100% dung lượng JavaScript client.

Vấn đề: Nỗi đau mang tên Client-side Mermaid#

Thông thường, thư viện astro-mermaid hoạt động theo mô hình:

  1. Khi build: Astro đọc khối mã ````mermaidvà chuyển thành thẻ HTML
    `.
  2. Khi người dùng truy cập: Trình duyệt phải tải toàn bộ thư viện mermaid.js (dung lượng từ 2MB đến 3MB sau khi giải nén).
  3. Thực thi: Trình duyệt kích hoạt engine tính toán layout phức tạp (Dagre, Elk, D3) để vẽ sơ đồ, gây tốn CPU trên thiết bị di động.
  4. Đổi giao diện Sáng/Tối: Mỗi lần người dùng chuyển dark/light mode, JavaScript lại phải chạy lại toàn bộ thuật toán để vẽ lại màu sắc.
Cách mới: remark-peleCách cũ: astro-mermaidMarkdown (.md)Astro BuildHTML chứa pre.mermaidTrình duyệt tải trangTải bundle mermaid.js(~2-3MB)Client chạy JS vẽ lại sơ đồ(Giật layout, tốn pin, chậm)Markdown (.md)Astro Build + PeleHTML nhúng sẵn thẻ SVGTrình duyệt hiển thị tức thì(0KB JS, Không layout shift)

[!WARNING] Nếu bạn đọc tắt JavaScript hoặc kết nối mạng chập chờn, biểu đồ Mermaid render ở client sẽ không thể hiển thị, chỉ để lại một khối văn bản mã nguồn khó hiểu.

Pele là gì? Giải thích dễ hiểu (ELI5)#

Hãy tưởng tượng bạn đặt mua một chiếc bàn ăn:

  • Client-side Mermaid giống như cửa hàng gửi đến nhà bạn một thùng gỗ phẳng kèm 100 con ốc vít và bản hướng dẫn: Trình duyệt của bạn đọc (khách hàng) phải tự loay hoay lắp ráp chiếc bàn trước khi có thể ngồi ăn.
  • Pele giống như xưởng gỗ đã hoàn thiện chiếc bàn tỉ mỉ trước khi giao: Khi thùng hàng mở ra, chiếc bàn đã sẵn sàng để sử dụng ngay lập tức mà không cần tốn chút công sức nào.

Pele ↗ là bộ công cụ render Mermaid được phát triển bởi kepano (CEO của Obsidian). Pele có những đặc điểm nổi bật:

  • Render đồng bộ (Synchronous): Chuyển chuỗi Mermaid thành mã SVG ngay lập tức trong Node.js hoặc Bun mà không cần trình duyệt headless (như Puppeteer).
  • Theme động bằng biến CSS: Các phần tử trong SVG sử dụng các biến CSS chuẩn như --pele-bg, --pele-fg, --pele-surface, --pele-border. Khi người dùng đổi Light/Dark mode, màu sắc biểu đồ tự động đổi ngay lập tức qua CSS mà không cần render lại.
  • Tương thích toàn diện: Hỗ trợ đầy đủ các dạng biểu đồ thông dụng: Flowchart, Sequence Diagram, Class Diagram, State Diagram, ER Diagram, Git Graph, Mindmap, v.v.

Hướng dẫn từng bước: Tích hợp Pele vào Astro#

Bước 1: Cài đặt Pele#

Cài đặt thư viện pele vào dự án:

bun add pele
# Hoặc npm: npm install pele
# Hoặc pnpm: pnpm add pele
bash

Bước 2: Tạo Remark Plugin remark-pele.ts#

Tạo file mới tại src/plugins/remark-pele.ts. Plugin này duyệt qua cây cú pháp Markdown (AST), tìm các khối mã có ngôn ngữ là mermaid và biến đổi chúng thành thẻ SVG nhờ Pele:

[!TIP] Việc sử dụng idPrefix: pele-${diagramIndex}- rất quan trọng. Khi một trang blog có nhiều sơ đồ, tùy chọn này giúp các định danh mũi tên (marker), dải màu (gradient) và đường cắt (clip-path) trong SVG không bị trùng lặp nhau.

Bước 3: Cấu hình astro.config.ts#

Trong file cấu hình astro.config.ts, gỡ bỏ tích hợp astroMermaid và đưa remarkPele vào danh sách remarkPlugins:

Bước 4: Tùy biến Theme bằng biến CSS#

Pele sử dụng các biến CSS để điều khiển màu sắc. Bạn có thể định nghĩa các giá trị này theo bảng màu của website trong file CSS toàn cục:

Và thêm quy tắc hiển thị responsive trong CSS:

Bước 5: Dọn dẹp mã nguồn và gỡ cài đặt gói cũ#

Bạn có thể xóa bỏ hoàn toàn đoạn mã script chạy mermaid.run() hoặc mermaid.initialize() trong layout (ví dụ: BaseLayout.astro) vì trình duyệt không còn phải chạy JavaScript để vẽ sơ đồ nữa.

Sau đó gỡ bỏ gói phụ thuộc cũ:

bun remove astro-mermaid mermaid
bash

Kết quả đạt được#

Tiêu chíTrước (astro-mermaid)Sau (pele)Cải thiện
Dung lượng JS tải ở Client~2.5 MB (bundle mermaid)0 KB-100%
Hiện tượng giật layout (CLS)Thường xuyên xuất hiện0 (Không giật)Tuyệt đối
Hỗ trợ khi tắt JSBiểu đồ bị lỗi / không hiệnHiển thị hoàn hảoĐộc lập JS
Tốc độ đổi Dark/Light modeChờ JS tính toán lạiTức thì (Pure CSS)Mượt mà
Thời gian buildN/A845 biểu đồ trong ~1.5sCực nhanh

Kết luận#

Bằng cách chuyển từ render Mermaid ở client sang render SVG tĩnh tại build-time với Pele, chúng ta đạt được tốc độ tải trang tối đa, trải nghiệm đọc liền mạch không giật khung hình và loại bỏ hoàn toàn gánh nặng bundle JavaScript cho người dùng di động.

Tài liệu tham khảo#