Thay thế astro-mermaid bằng Pele: SVG tại Build-time
Cách thay thế astro-mermaid bằng Pele để render biểu đồ Mermaid thành SVG tĩnh ngay khi build, giảm 0KB JavaScript và tối ưu hiệu năng.
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:
- Khi build: Astro đọc khối mã ````mermaid
và chuyển thành thẻ HTML`.
- 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). - 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.
- Đổ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.
[!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 pelebashBướ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:
import type { Code, Root } from 'mdast';
import { render, type RenderOptions } from 'pele';
import { visit } from 'unist-util-visit';
export interface RemarkPeleOptions {
fontSize?: number;
fontFamily?: string;
renderOptions?: RenderOptions;
}
function escapeHtml(str: string): string {
return str
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
export default function remarkPele(options: RemarkPeleOptions = {}) {
const defaultFontSize = options.fontSize ?? 14;
const defaultFontFamily = options.fontFamily ?? 'Inter, system-ui, sans-serif';
return (tree: Root) => {
let diagramIndex = 0;
visit(tree, 'code', (node: Code, index, parent) => {
if (
node.lang &&
node.lang.trim().toLowerCase() === 'mermaid' &&
parent &&
typeof index === 'number'
) {
try {
diagramIndex++;
const idPrefix = `pele-${diagramIndex}-`;
const { svg } = render(node.value, {
idPrefix,
responsive: true,
fontSize: defaultFontSize,
fontFamily: defaultFontFamily,
...options.renderOptions,
});
// Thay thế khối mã bằng container chứa SVG
parent.children[index] = {
type: 'html',
value: `<div class="pele-diagram my-6 flex justify-center overflow-x-auto">${svg}</div>`,
};
} catch (err: unknown) {
const error = err as Error;
console.warn(`[remark-pele] Lỗi render biểu đồ:`, error?.message);
parent.children[index] = {
type: 'html',
value: `<div class="pele-error my-4 rounded-lg border border-red-500/50 bg-red-500/10 p-4"><p class="mb-2 font-mono text-xs text-red-500">Mermaid Render Error: ${escapeHtml(error?.message || String(err))}</p><pre class="overflow-x-auto text-xs"><code>${escapeHtml(node.value)}</code></pre></div>`,
};
}
}
});
};
}ts[!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:
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkPele from './src/plugins/remark-pele.ts';
import astroMermaid from 'astro-mermaid';
export default defineConfig({
markdown: {
processor: unified({
remarkPlugins: [
remarkMath,
remarkPele,
],
rehypePlugins: [ /* ... */ ],
}),
},
integrations: [
astroMermaid({ /* ... */ }),
AstroPureIntegration(config),
],
});tsBướ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:
:root {
/* Pele Mermaid theme tokens (Light mode) */
--pele-font: Inter, system-ui, -apple-system, sans-serif;
--pele-font-mono: monospace;
--pele-radius: var(--radius);
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}
.dark,
[data-theme="dark"] {
/* Pele Mermaid theme tokens (Dark mode) */
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}cssVà thêm quy tắc hiển thị responsive trong CSS:
.pele-diagram {
margin-block: 1.75rem;
display: flex;
justify-content: center;
align-items: center;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
border-radius: var(--radius, 0.5rem);
padding: 0.5rem;
}
.pele-diagram svg.pele {
max-width: 100%;
height: auto;
display: block;
}cssBướ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 mermaidbashKế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ện | 0 (Không giật) | Tuyệt đối |
| Hỗ trợ khi tắt JS | Biểu đồ bị lỗi / không hiện | Hiển thị hoàn hảo | Độc lập JS |
| Tốc độ đổi Dark/Light mode | Chờ JS tính toán lại | Tức thì (Pure CSS) | Mượt mà |
| Thời gian build | N/A | 845 biểu đồ trong ~1.5s | Cự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.