Mermaid ASCII: Kết xuất sơ đồ Mermaid trong terminal

 (github.com/lukilabs)
16 điểm bởi GN⁺ 2026-01-30 | 1 bình luận | Chia sẻ qua WhatsApp
  • beautiful-mermaid là công cụ siêu nhanh viết bằng TypeScript để kết xuất sơ đồ Mermaid thành SVG hoặc ASCII art
  • Hỗ trợ 5 loại sơ đồ (Flowchart, State, Sequence, Class, ER) và hoạt động cả trong terminal lẫn trình duyệt
  • Có 15 theme tích hợp sẵn và tương thích Shiki, cho phép áp dụng trực tiếp theme VS Code
  • Chế độ Mono cung cấp cách thể hiện hình ảnh nhất quán chỉ với hai màu, đồng thời hỗ trợ chuyển đổi theme theo thời gian thực bằng thuộc tính tùy chỉnh CSS
  • Nổi bật như một công cụ nhẹ, không phụ thuộc, giúp trực quan hóa luồng dữ liệu và cấu trúc hệ thống trong môi trường lập trình có AI hỗ trợ

Tổng quan

  • beautiful-mermaid là công cụ kết xuất sơ đồ Mermaid thành SVG hoặc văn bản ASCII/Unicode
    • Hoạt động không cần phụ thuộc DOM và hỗ trợ kết xuất siêu nhanh (hơn 100 sơ đồ trong vòng 500ms)
    • Được đội ngũ Craft phát triển cho Craft Agents
  • Là bản port sang TypeScript của Mermaid-ascii (dự án viết bằng Go) và được mở rộng thêm tính năng
    • Bổ sung hỗ trợ sơ đồ Sequence, Class, ER
    • Bao gồm ký tự khung Unicode, cấu hình khoảng cách và phần đệm

Tính năng chính

  • Các loại sơ đồ được hỗ trợ: Flowchart, State, Sequence, Class, ER
  • Định dạng đầu ra: SVG (cho UI phong phú), ASCII/Unicode (cho terminal)
  • Hệ thống theme
    • Cung cấp 15 theme tích hợp (tokyo-night, dracula, nord, github-dark...)
    • Chế độ Mono: tự động suy ra toàn bộ màu sắc chỉ từ hai màu nền (bg) và tiền cảnh (fg)
    • Chế độ Enriched: có thể chỉ định thêm các màu tùy chọn như accent, muted, surface, border
    • Hỗ trợ chuyển đổi theo thời gian thực dựa trên thuộc tính tùy chỉnh CSS
  • Tích hợp Shiki
    • Tự động ánh xạ màu từ theme VS Code sang màu sơ đồ
    • Có thể trích xuất bg, fg, accent... bằng hàm fromShikiTheme()

Cài đặt và sử dụng

  • Lệnh cài đặt
    • npm install beautiful-mermaid hoặc bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • Ví dụ kết xuất SVG 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • Ví dụ kết xuất ASCII 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • Sử dụng trên trình duyệt
    • Có thể tải trực tiếp qua thẻ <script> bằng CDN (unpkg, jsDelivr)
    • Có thể truy cập renderMermaid, renderMermaidAscii, THEMES... từ đối tượng toàn cục beautifulMermaid

Đầu ra ASCII và tùy chọn

  • Hỗ trợ chế độ Unicode (mặc định) và chế độ ASCII thuần
  • Các tùy chọn
    • useAscii: có dùng ASCII hay không
    • paddingX, paddingY: khoảng cách giữa các node
    • boxBorderPadding: phần đệm bên trong node
  • Ví dụ đầu ra 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

Tóm tắt API

  • renderMermaid(text, options?): kết xuất sơ đồ Mermaid thành SVG
    • Tùy chọn: bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?): kết xuất thành văn bản ASCII/Unicode
  • fromShikiTheme(theme): trích xuất màu từ theme Shiki
  • THEMES: đối tượng gồm 15 theme tích hợp
  • DEFAULTS: màu mặc định (#FFFFFF, #27272A)

Giấy phép và tác giả

  • Giấy phép MIT
  • Do đội ngũ Craft phát triển
  • Engine ASCII dựa trên: mermaid-ascii của Alexander Grooff

Ý nghĩa kỹ thuật

  • Trong môi trường trợ lý lập trình AI, có thể trực quan hóa ngay sơ đồ bên trong terminal hoặc giao diện chat
  • Với cấu trúc nhẹ, nhanh, không phụ thuộc, công cụ đặc biệt hữu ích trong môi trường CLI hoặc server
  • Khả năng mở rộng theme và tính tương thích giúp cải thiện trải nghiệm nhà phát triển

Bài viết liên quan

1 bình luận

 
GN⁺ 2026-01-30
Ý kiến trên Hacker News

  • Dự án dựa trên thư viện Go mermaid-ascii do Alexander Grooff tạo ra thực sự rất ấn tượng
    Tuy nhiên, đã phát hiện lỗi cạnh "start" không được render
    Việc thử nghiệm được thực hiện tại agents.craft.do/mermaid

  • Tôi không thật sự hiểu vì sao sơ đồ ASCII gần đây lại được chú ý trở lại
    Mermaid hay PlantUML vốn đã là dạng văn bản, nên đa số người dùng muốn sơ đồ tiêu chuẩn dễ cho con người đọc hơn là cho máy
    ASCII bị giới hạn bởi các ký tự có thể in được nên khả năng biểu đạt kém hơn và cũng khó tiêu chuẩn hóa

    • Còn tùy ngữ cảnh. Ví dụ trong README hoặc đầu ra CLI, nơi không thể render Mermaid, thì ASCII là lựa chọn tốt nhất về tính dễ đọc
    • Có thể chèn sơ đồ ASCII vào trong chú thích mã nguồn. Nó cũng hiển thị tốt trong các công cụ chạy trên terminal như Claude Code
    • Không phải là “ASCII vô dụng”, mà trong quy trình làm việc thiên về văn bản (ví dụ: Org Mode, quản lý kho Git) thì ngược lại còn rất hữu ích
      Vì không cần quản lý file ảnh hay những thiết lập phức tạp như Git LFS
    • Việc không cần trình render cũng là một lợi thế. Ngay trong tài liệu Markdown hay mã nguồn cũng có thể đọc ở dạng đã được “render” sẵn
    • Vì nhiều lập trình viên và coding agent chủ yếu dùng Markdown và môi trường CLI, nên cách tiếp cận ASCII như vậy là rất tự nhiên

  • Tôi thực sự rất thích sơ đồ ASCII
    Dù xem bằng cat trong terminal hay render trên website thì nó vẫn trông đẹp như nhau, đó là điểm cuốn hút
    Chỉ cần có một font monospaced tốt là nhìn cũng rất gọn gàng
    Cũng xin đề xuất Monodraw, một ứng dụng tạo sơ đồ ASCII

    • ^Unicode
    • Điểm tôi đặc biệt thích là có thể đặt sơ đồ ở đầu mã nguồn

  • Trình render Mermaid ASCII thực tế được chuyển sang từ dự án AlexanderGrooff/mermaid-ascii
    Dự án này đã chuyển nó sang TypeScript và thêm theme riêng

    • Thật ra có lẽ chỉ cần bundle mermaid-ascii bằng WASM là được
      Thuật toán chính gần như được chuyển đổi 1:1, nên có vẻ Claude đã không mất đến một giờ để port sang TS
      Có thể so sánh mã Go và mã TS
    • Cảm ơn vì đã ghi công
    • Vì làm trên Go nên cũng chẳng cần đến mấy câu đùa về quản lý package. Tôi định tích hợp nó vào debugger của mình
    • Có người chỉ ra rằng có thể AI đã sao chép cả dự án rồi chỉ đổi tên
    • Liên kết gốc đã được sửa lại. Có vẻ người đăng đã chia sẻ với thiện chí

  • Mermaid đang được chú ý, nhưng Kroki(kroki.io) hỗ trợ nhiều định dạng sơ đồ hơn rất nhiều
    Nó bao gồm gần như mọi loại sơ đồ văn bản như BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz, v.v.
    Trình soạn thảo Markdown KeenWrite(keenwrite.com) của tôi tích hợp Kroki như một dịch vụ, nên khi có định dạng mới được thêm vào thì có thể dùng ngay tự động
    Mermaid dùng <foreignObject>, nên phần lớn thư viện đều khó render nó

    • So sánh MermaidJS với Kroki cũng gần giống như so sánh PDF.js với Adobe Acrobat
      MermaidJS chạy nhanh và cục bộ ngay trong trang web, còn Kroki thì phụ thuộc vào dịch vụ bên ngoài
      Nếu không cần sơ đồ quá phức tạp thì Mermaid là lựa chọn đơn giản hơn
    • Trước đây tôi từng tạo một công cụ tên là phart để render NetworkX DAG sang ASCII
      Trong ví dụ README có nhiều đầu ra khác nhau như đồ thị cờ vua
    • Ban đầu tôi thấy thiết kế của Kroki không ổn vì đổ bóng và méo font quá nặng, nhưng sau đó mới biết là do hiểu lầm
      Dù vậy, tôi vẫn thấy style mặc định của Mermaid gọn gàng hơn
      Nhân tiện, KeenWrite trông khá tuyệt

  • Cũng có công cụ Diagon để chuyển văn bản thành sơ đồ ASCII
    Tôi cũng có danh sách các công cụ văn bản→sơ đồ do mình tổng hợp, nhưng công cụ chuyển văn bản→ASCII thì không nhiều

    • Có người cảm ơn và nói đây là một danh sách rất hay

  • Có vẻ để chạy live demo thì cần tải nền tảng AI agent về
    Hơi tiếc là không thể dùng thử ngay mà không cần cài đặt

    • Sẽ rất tốt nếu các nhà phát triển làm một demo chỉ chạy phía client dựa trên GitHub Pages
      Xét theo cấu trúc dự án thì điều đó có vẻ hoàn toàn khả thi

  • Có tính năng “Subgraph Direction Override”, cho phép đặt hướng khác nhau cho subgraph
    Nhờ đó có thể giả lập sơ đồ swim lane mà Mermaid vốn không hỗ trợ

  • Selkie do tôi tạo là một dự án thử nghiệm triển khai hoàn chỉnh parser và renderer Mermaid bằng Rust
    Ban đầu nó được dùng để thử xem Claude Code có thể làm đến đâu, và kết quả thật đáng ngạc nhiên
    Có thể chạy trực tiếp trên Playground
    Nếu hỗ trợ terminal Kitty thì còn có thể xuất sơ đồ trực tiếp ra terminal
    Tôi sẽ sớm viết blog tổng kết toàn bộ quá trình

  • Dự án này thực sự rất hay, và sự cộng hưởng với Claude Code cũng rất ấn tượng
    Tôi từng làm một dự án tương tự nhưng tập trung vào khám phá mã tương tác thay vì ASCII
    Nó được thiết kế để hỗ trợ con người hiểu tốt hơn, dùng D2 và cũng đang chuẩn bị hỗ trợ Mermaid
    Tôi muốn nghe ý kiến xem tính tương tác cho con người có giá trị hơn, hay ngữ cảnh cho agent mới là điều quan trọng hơn
    Liên kết dự án