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

1 week ago 5

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 등 접근 가능

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

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)