Toollance

Mermaid sang ASCII: Sơ đồ sống sót được trong plain text

dev-toolswebassemblydocumentation

Simon Willison vừa công bố một tool chạy trên trình duyệt chuyển cú pháp sơ đồ Mermaid thành ASCII và Unicode box-drawing art. Nó là một lớp bọc mỏng quanh AlexanderGrooff/mermaid-ascii, một thư viện Go được compile sang WebAssembly để chạy hoàn toàn client-side.

Phần thú vị không nằm ở cái tool. Nó nằm ở câu hỏi mà tool này đặt ra: tại sao lại có người muốn một sơ đồ xấu hơn?

Sơ đồ được render có vấn đề về phân phối

Mermaid rất tốt khi có thứ gì đó render nó. GitHub render nó trong Markdown. Nhiều docs site và app ghi chú cũng vậy.

Vấn đề là ở mọi nơi còn lại. Một code block Mermaid là không thể đọc được trong:

Ở tất cả những chỗ đó, một block Mermaid thoái hoá thành một bức tường cú pháp mà người đọc phải tự compile trong đầu. ASCII art thì thoái hoá thành… một cái sơ đồ. Toàn bộ lập luận nằm ở đó.

Cái giá phải trả là có thật

Sơ đồ ASCII thực sự xấu hơn và yếu hơn. Bạn mất đường cong, khoảng cách chính xác, hình dạng tuỳ ý, và mọi sơ đồ phức tạp đến mức ký tự box-drawing không diễn tả nổi. Không ai nên chuyển một sơ đồ kiến trúc bốn mươi node sang ASCII rồi gọi đó là cải tiến.

Vùng phù hợp thì hẹp: vài cái hộp, một hướng luồng rõ ràng, vài cạnh có nhãn. Đúng loại sơ đồ hay nằm trong code comment hoặc README — và cũng đúng loại thường bị bỏ qua ngày nay vì nhúng sơ đồ vào đó quá bất tiện.

Chỗ đứng của nó trong workflow thật

Cách làm thực tế là giữ Mermaid làm nguồn chân lý, và sinh ra ASCII ở nơi plain text là định dạng phân phối:

Mermaid source (trong docs, có version control)
        │
        ├──► render SVG    → docs site, README trên GitHub
        │
        └──► ASCII art     → code comment, CLI help, commit message

Chính cái sơ đồ đó là minh chứng — bạn đang đọc nó trong một file Markdown, trong một code block, không có renderer nào tham gia.

Còn một lý do thứ hai khiến chuyện này quan trọng hơn ở năm 2026 so với vài năm trước: sơ đồ plain text nằm rất gọn trong context window của LLM. Khi bạn dán một file vào coding agent, một sơ đồ ASCII trong comment được đọc như cấu trúc. Một code block Mermaid được đọc như cú pháp mà model phải parse trước khi nó có nghĩa. Nếu bạn giữ ghi chú kiến trúc trong comment để chính agent của mình đọc, ASCII là định dạng thân thiện hơn.

Chúng tôi không có benchmark nào cho khẳng định này — đó là suy luận hợp lý từ cách các công cụ này tiêu thụ text, không phải kết quả đo được. Hãy coi nó là một giả thuyết đáng thử trên codebase của bạn, đừng coi là sự thật đã được chứng minh.

WebAssembly âm thầm là câu trả lời đúng ở đây

Chi tiết triển khai đáng chú ý: đây là một thư viện Go vốn chưa từng được viết cho trình duyệt, được compile sang WASM và ship dưới dạng một trang tĩnh. Không server, không API key, không upload.

Mô hình đó đang dần thành mặc định cho các tiện ích dành cho developer. Bất cứ thứ gì thuần tính toán trên text bạn đã có sẵn — format, convert, hash, encode — đều không có lý do gì để đi một vòng qua mạng. Cùng lập luận đó là lý do JSON formatter và Base64 encoder của chúng tôi chạy trong trình duyệt bạn thay vì trên server. Dữ liệu không rời khỏi tab, và tool vẫn chạy khi offline.

Một tool anh em, grok-mermaid, dùng cách tiếp cận tương tự bằng Rust cho Unicode box art. Chúng tôi chưa thử nó nên không thể so sánh chất lượng output.

Thử đi

Bản demo ở tools.simonwillison.net/mermaid-ascii, thư viện nền ở GitHub.

Bắt đầu bằng một sơ đồ bạn đã có sẵn trong README và dán vào. Nếu bản ASCII đọc được, khả năng cao nó cũng nên nằm trong code — gần hơn với thứ mà nó mô tả, nơi nó thực sự được nhìn thấy.

Nguồn: mermaid-ascii và grok-mermaid trên blog của Simon Willison.