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

> Clean Markdown view of GeekNews topic #26245. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=26245](https://news.hada.io/topic?id=26245)
- GeekNews Markdown: [https://news.hada.io/topic/26245.md](https://news.hada.io/topic/26245.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-01-30T09:57:19+09:00
- Updated: 2026-01-30T09:57:19+09:00
- Original source: [github.com/lukilabs](https://github.com/lukilabs/beautiful-mermaid)
- Points: 16
- Comments: 1

## Summary

**beautiful‑mermaid**는 Mermaid 다이어그램을 **SVG 또는 ASCII 아트**로 초고속 렌더링하는 TypeScript 기반 도구입니다. DOM 의존성 없이 작동하며, 터미널과 브라우저 모두에서 5가지 다이어그램 유형을 지원합니다. **Shiki 테마 연동**과 **Mono 모드**를 통해 VS Code 색상 체계를 그대로 반영하거나 최소 색상으로 일관된 시각 표현을 유지할 수 있습니다. AI 보조 코딩 환경에서 데이터 흐름과 시스템 구조를 가볍게 시각화하려는 개발자에게 실용적인 선택지로 자리합니다.

## Topic Body

- **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 렌더링 예시**
  ```ts
  import { renderMermaid } from 'beautiful-mermaid'
  const svg = await renderMermaid(`graph TD; A-->B;`)
  ```
- **ASCII 렌더링 예시**
  ```ts
  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 도구나 서버 환경에서도 활용도 높음  
- **테마 확장성과 호환성**을 통해 개발자 경험 향상

## Comments



### Comment 50246

- Author: neo
- Created: 2026-01-30T09:57:19+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=46804828) 
- Alexander Grooff가 만든 Go 라이브러리 [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii)를 기반으로 한 프로젝트가 정말 멋짐  
  다만 **"start" 엣지가 렌더링되지 않는 버그**를 발견했음  
  테스트는 [agents.craft.do/mermaid](https://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](https://monodraw.helftone.com/)라는 ASCII 다이어그램 제작 앱도 추천함  
  - ^Unicode  
  - 소스 코드 상단에 다이어그램을 넣을 수 있다는 점이 특히 좋음  

- 실제 Mermaid ASCII 렌더러는 [AlexanderGrooff/mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) 프로젝트에서 옮겨온 것임  
  이 프로젝트는 그걸 **TypeScript로 변환**하고 자체 테마를 추가했음  
  - 사실 그냥 mermaid-ascii를 **WASM으로 번들링**해도 됐을 듯함  
    주요 알고리즘은 거의 1:1 변환이라, Claude가 TS로 포팅하는 데 한 시간도 안 걸렸을 것 같음  
    [Go 코드](https://github.com/AlexanderGrooff/mermaid-ascii/blob/master/cmd/draw.go#L170-L238)와 [TS 코드](https://github.com/lukilabs/beautiful-mermaid/blob/main/src/ascii/draw.ts#L30-L80)를 비교해볼 수 있음  
  - 크레딧에 감사함  
  - Go 기반이라 **패키지 관리** 농담도 필요 없음. 내 디버거에 통합할 예정임  
  - 누군가 AI가 전체 프로젝트를 복사하고 이름만 바꿔 단 거 아니냐고 지적함  
  - 원본 링크를 수정했음. 제출자는 선의로 올린 것으로 보임  

- Mermaid가 주목받고 있지만, **Kroki**([kroki.io](https://kroki.io/))는 훨씬 다양한 다이어그램 포맷을 지원함  
  BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz 등 거의 모든 텍스트 기반 다이어그램을 포함함  
  내 Markdown 에디터 **KeenWrite**([keenwrite.com](https://keenwrite.com/))는 Kroki를 서비스로 통합해서, 새 포맷이 추가되면 자동으로 사용 가능함  
  Mermaid는 `<foreignObject>`를 사용하기 때문에 대부분의 라이브러리에서 렌더링이 어려움  
  - MermaidJS와 Kroki를 비교하는 건 **PDF.js와 Adobe Acrobat**을 비교하는 것과 비슷함  
    MermaidJS는 웹페이지 내에서 빠르고 로컬로 실행되지만, Kroki는 외부 서비스 의존성이 있음  
    복잡한 다이어그램이 필요하지 않다면 Mermaid가 더 간단한 선택임  
  - 예전에 **NetworkX DAG를 ASCII로 렌더링**하려고 phart라는 도구를 만들었음  
    [README 예시](https://github.com/scottvr/phart/blob/main/README.md#examples)에 체스 그래프 등 다양한 출력 예시가 있음  
  - 처음엔 Kroki의 디자인이 너무 **그림자와 폰트 왜곡**이 심해서 별로라고 생각했지만, 나중에 오해였음을 알게 됨  
    그래도 Mermaid의 기본 스타일이 더 깔끔하다고 느낌  
    참고로 KeenWrite는 꽤 훌륭해 보임  

- 텍스트를 ASCII 다이어그램으로 변환하는 도구 [Diagon](https://arthursonzogni.com/Diagon)도 있음  
  내가 정리한 [텍스트→다이어그램 도구 목록](https://xosh.org/text-to-diagram/)도 있는데, 텍스트→ASCII 변환 도구는 많지 않음  
  - 좋은 리스트라며 감사 인사를 받음  

- 라이브 데모를 실행하려면 **AI 에이전트 플랫폼 다운로드**가 필요한 것 같음  
  설치 없이 바로 써보고 싶은데 그게 안 되는 게 아쉬움  
  - 개발자들이 **GitHub Pages 기반 클라이언트 전용 데모**를 만들어주면 좋겠음  
    프로젝트 구조상 충분히 가능해 보임  

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

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

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