▲

Mermaid ASCII: 터미널에서 Mermaid 다이어그램 렌더링

 (github.com/lukilabs)
12P by GN⁺ 18시간전 | ★ favorite | 댓글 1개
  • beautiful-mermaid는 Mermaid 다이어그램을 SVG 또는 ASCII 아트로 렌더링하는 초고속 TypeScript 기반 도구
  • 5가지 다이어그램 유형(Flowchart, State, Sequence, Class, ER)을 지원하며, 터미널과 브라우저 모두에서 작동
  • 15개 내장 테마와 Shiki 호환성을 통해 VS Code 테마를 직접 적용 가능
  • Mono 모드로 단 두 가지 색상만으로도 일관된 시각 표현을 제공하며, CSS 커스텀 속성으로 실시간 테마 전환 지원
  • AI 보조 프로그래밍 환경에서 데이터 흐름과 시스템 구조를 시각화할 수 있는 경량·무의존형 도구로 중요성 부각

개요

  • beautiful-mermaid는 Mermaid 다이어그램을 SVG 또는 ASCII/Unicode 텍스트로 렌더링하는 도구
    • DOM 의존성 없이 작동하며, 초고속 렌더링(500ms 내 100개 이상 다이어그램) 지원
    • Craft 팀이 Craft Agents용으로 개발
  • Mermaid-ascii(Go 기반 프로젝트)를 TypeScript로 포팅하고 기능 확장
    • Sequence, Class, ER 다이어그램 지원 추가
    • Unicode 박스 문자, 간격 및 패딩 설정 기능 포함

주요 기능

  • 지원 다이어그램 유형: Flowchart, State, Sequence, Class, ER
  • 출력 형식: SVG(리치 UI용), ASCII/Unicode(터미널용)
  • 테마 시스템
    • 15개 내장 테마 제공 (tokyo-night, dracula, nord, github-dark 등)
    • Mono 모드: 배경(bg)과 전경(fg) 두 색상만으로 전체 색상 자동 파생
    • Enriched 모드: accent, muted, surface, border 등 선택적 색상 지정 가능
    • CSS 커스텀 속성 기반 실시간 전환 지원
  • Shiki 통합
    • VS Code 테마 색상을 다이어그램 색상으로 자동 매핑
    • fromShikiTheme() 함수로 bg, fg, accent 등 추출 가능

설치 및 사용

  • 설치 명령
    • npm install beautiful-mermaid 또는 bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • SVG 렌더링 예시 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • ASCII 렌더링 예시 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • 브라우저 사용
    • CDN(unpkg, jsDelivr)을 통해 <script> 태그로 직접 로드 가능
    • 전역 객체 beautifulMermaid에서 renderMermaid, renderMermaidAscii, THEMES 등 접근 가능

ASCII 출력 및 옵션

  • Unicode 모드(기본)와 순수 ASCII 모드 지원
  • 옵션 항목
    • useAscii: ASCII 사용 여부
    • paddingX, paddingY: 노드 간 간격
    • boxBorderPadding: 노드 내부 여백
  • 예시 출력 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

API 요약

  • renderMermaid(text, options?): Mermaid 다이어그램을 SVG로 렌더링
    • 옵션: bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?): ASCII/Unicode 텍스트로 렌더링
  • fromShikiTheme(theme): Shiki 테마에서 색상 추출
  • THEMES: 15개 내장 테마 객체
  • DEFAULTS: 기본 색상 (#FFFFFF, #27272A)

라이선스 및 제작

  • MIT 라이선스
  • Craft 팀 제작
  • ASCII 엔진 기반: Alexander Grooff의 mermaid-ascii

기술적 의의

  • AI 코딩 어시스턴트 환경에서 다이어그램을 터미널이나 채팅 인터페이스 내에서 즉시 시각화 가능
  • 경량·고속·무의존성 구조로, CLI 도구나 서버 환경에서도 활용도 높음
  • 테마 확장성과 호환성을 통해 개발자 경험 향상
▲
GN⁺ 18시간전  [-]
Hacker News 의견들

  • Alexander Grooff가 만든 Go 라이브러리 mermaid-ascii를 기반으로 한 프로젝트가 정말 멋짐
    다만 "start" 엣지가 렌더링되지 않는 버그를 발견했음
    테스트는 agents.craft.do/mermaid에서 진행했음

  • 왜 요즘 ASCII 다이어그램이 다시 주목받는지 잘 모르겠음
    Mermaid나 PlantUML도 이미 텍스트 기반이라, 대부분의 사용자는 기계보다는 사람이 보기 좋은 표준 다이어그램을 원함
    ASCII는 인쇄 가능한 문자에 제한되어 있어서 표현력이 떨어지고 표준화도 어려움

    • 문맥에 따라 다름. 예를 들어 README나 CLI 출력처럼 Mermaid 렌더링이 불가능한 환경에서는 ASCII가 가독성 면에서 최선의 선택임
    • 코드 주석 안에 ASCII 다이어그램을 넣을 수 있음. Claude Code 같은 터미널 기반 도구에서도 잘 보임
    • “ASCII가 쓸모없다”기보다는, 텍스트 중심 워크플로우(예: Org Mode, Git 저장소 관리)에선 오히려 유용함
      이미지 파일 관리나 Git LFS 같은 복잡한 설정이 필요 없기 때문임
    • 렌더러가 필요 없다는 점이 장점임. Markdown 문서나 소스 코드 안에서도 바로 “렌더링된” 형태로 읽을 수 있음
    • 많은 개발자와 코딩 에이전트들이 Markdown과 CLI 환경을 주로 쓰기 때문에, 이런 ASCII 접근이 자연스러움

  • 나는 ASCII 다이어그램을 정말 좋아함
    터미널에서 cat으로 보든 웹사이트에서 렌더링하든 똑같이 멋지게 보이는 게 매력임
    좋은 monospaced 폰트만 있으면 시각적으로도 깔끔함
    Monodraw라는 ASCII 다이어그램 제작 앱도 추천함

    • ^Unicode
    • 소스 코드 상단에 다이어그램을 넣을 수 있다는 점이 특히 좋음

  • 실제 Mermaid ASCII 렌더러는 AlexanderGrooff/mermaid-ascii 프로젝트에서 옮겨온 것임
    이 프로젝트는 그걸 TypeScript로 변환하고 자체 테마를 추가했음

    • 사실 그냥 mermaid-ascii를 WASM으로 번들링해도 됐을 듯함
      주요 알고리즘은 거의 1:1 변환이라, Claude가 TS로 포팅하는 데 한 시간도 안 걸렸을 것 같음
      Go 코드와 TS 코드를 비교해볼 수 있음
    • 크레딧에 감사함
    • Go 기반이라 패키지 관리 농담도 필요 없음. 내 디버거에 통합할 예정임
    • 누군가 AI가 전체 프로젝트를 복사하고 이름만 바꿔 단 거 아니냐고 지적함
    • 원본 링크를 수정했음. 제출자는 선의로 올린 것으로 보임

  • Mermaid가 주목받고 있지만, Kroki(kroki.io)는 훨씬 다양한 다이어그램 포맷을 지원함
    BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz 등 거의 모든 텍스트 기반 다이어그램을 포함함
    내 Markdown 에디터 KeenWrite(keenwrite.com)는 Kroki를 서비스로 통합해서, 새 포맷이 추가되면 자동으로 사용 가능함
    Mermaid는 <foreignObject>를 사용하기 때문에 대부분의 라이브러리에서 렌더링이 어려움

    • MermaidJS와 Kroki를 비교하는 건 PDF.js와 Adobe Acrobat을 비교하는 것과 비슷함
      MermaidJS는 웹페이지 내에서 빠르고 로컬로 실행되지만, Kroki는 외부 서비스 의존성이 있음
      복잡한 다이어그램이 필요하지 않다면 Mermaid가 더 간단한 선택임
    • 예전에 NetworkX DAG를 ASCII로 렌더링하려고 phart라는 도구를 만들었음
      README 예시에 체스 그래프 등 다양한 출력 예시가 있음
    • 처음엔 Kroki의 디자인이 너무 그림자와 폰트 왜곡이 심해서 별로라고 생각했지만, 나중에 오해였음을 알게 됨
      그래도 Mermaid의 기본 스타일이 더 깔끔하다고 느낌
      참고로 KeenWrite는 꽤 훌륭해 보임

  • 텍스트를 ASCII 다이어그램으로 변환하는 도구 Diagon도 있음
    내가 정리한 텍스트→다이어그램 도구 목록도 있는데, 텍스트→ASCII 변환 도구는 많지 않음

    • 좋은 리스트라며 감사 인사를 받음

  • 라이브 데모를 실행하려면 AI 에이전트 플랫폼 다운로드가 필요한 것 같음
    설치 없이 바로 써보고 싶은데 그게 안 되는 게 아쉬움

    • 개발자들이 GitHub Pages 기반 클라이언트 전용 데모를 만들어주면 좋겠음
      프로젝트 구조상 충분히 가능해 보임

  • “Subgraph Direction Override” 기능이 있어서, 서브그래프 방향을 다르게 설정할 수 있음
    이걸로 Mermaid가 지원하지 않던 swim lane 다이어그램을 흉내낼 수 있음

  • 내가 만든 Selkie는 Mermaid 파서와 렌더러를 Rust로 완전 구현한 실험 프로젝트임
    Claude Code로 얼마나 가능한지 테스트하는 용도였는데, 결과가 놀라움
    Playground에서 바로 실행 가능함
    Kitty 터미널을 지원하면 다이어그램을 직접 터미널에 출력할 수도 있음
    곧 전체 과정을 블로그로 정리할 예정임

  • 이 프로젝트는 정말 멋지고, Claude Code와의 시너지도 인상적임
    나는 비슷한 프로젝트를 했는데, ASCII 대신 인터랙티브 코드 탐색에 초점을 맞췄음
    인간의 이해를 돕는 방향으로 설계했고, D2를 사용했으며 Mermaid 지원도 준비 중임
    사람을 위한 인터랙티브성이 더 가치 있는지, 아니면 에이전트 컨텍스트가 중요한지에 대한 의견을 듣고 싶음
    프로젝트 링크

답변달기