Mermaid를 터미널 그림으로 바꾸는 이유: grok-mermaid

Mermaid는 다이어그램을 텍스트로 작성하게 해주는 문법입니다. 보통은 이를 SVG나 이미지로 렌더링해 문서에 넣습니다. 반면 grok-mermaid는 Mermaid 다이어그램을 유니코드 박스 아트로 바꿔 보여줍니다. 즉, 다이어그램을 이미지가 아니라 터미널에서 읽을 수 있는 텍스트 그림으로 만드는 도구입니다.¹

흥미로운 점은 구현 방식입니다. grok-mermaid는 xai-grok-markdown/src/mermaid.rs에 있는 Rust 기반 Mermaid 터미널 렌더러를 WebAssembly로 컴파일해 브라우저에서 시험할 수 있게 한 사례입니다.¹ 결과적으로 “Mermaid를 어디까지 텍스트 환경에 가져올 수 있는가”를 보여주는 작은 실험이자 실용 도구입니다.

유니코드 박스 아트가 필요한 이유

유니코드 박스 드로잉 문자는 텍스트 사용자 인터페이스에서 선, 상자, 프레임을 그리기 위해 쓰이는 세미그래픽 문자입니다. ┌, ─, │, ┘ 같은 문자가 대표적입니다. 이 문자들은 인접한 문자와 가로 또는 세로로 자연스럽게 이어지도록 설계되어 있습니다.²

다만 제대로 보이려면 정렬이 중요합니다. 그래서 보통 고정폭 글꼴에서 가장 안정적으로 동작합니다.² 폰트나 터미널 환경이 맞지 않으면 선이 어긋나고, 다이어그램의 구조도 읽기 어려워집니다.

GUI에서는 선과 사각형을 그래픽 API로 직접 그릴 수 있습니다. 하지만 CLI, SSH 세션, CI 로그, 코드 리뷰, README의 평문 영역에서는 이미지가 오히려 불편할 때가 많습니다. 이런 환경에서는 복사하고 검색하고 diff로 비교할 수 있는 텍스트 다이어그램이 실용적입니다.

grok-mermaid가 보여주는 변화

grok-mermaid의 핵심은 Mermaid를 “이미지로만 보는 문법”에서 “터미널에서도 읽을 수 있는 구조 표현”으로 확장한다는 데 있습니다. Mermaid 소스는 그대로 텍스트이고, 출력도 다시 텍스트가 됩니다. 문서화 과정 전체가 텍스트 중심으로 유지되는 셈입니다.

이 접근은 특히 다음 환경에서 가치가 있습니다.

• 터미널 기반 개발 도구

• 로그와 CI 출력

• CLI에서 동작하는 AI 에이전트 응답

• 코드 주석이나 평문 문서

• 이미지 첨부가 번거로운 리뷰 환경

박스 드로잉 문자는 소스 코드 안의 평문 주석에도 사용할 수 있습니다.² 따라서 간단한 흐름도나 관계도를 코드 가까이에 남기고 싶을 때도 유용합니다.

중요한 것은 박스 아트가 SVG나 PNG를 완전히 대체한다는 뜻은 아니라는 점입니다. 발표 자료, 웹 문서, 정교한 시각 디자인이 필요한 곳에서는 여전히 그래픽 출력이 적합합니다. 반대로 빠르게 구조를 확인하고 공유해야 하는 텍스트 환경에서는 유니코드 박스 아트가 더 가볍고 다루기 쉽습니다.

사용할 때 확인할 기준

grok-mermaid 같은 도구를 실무에 적용할 때는 몇 가지 조건을 먼저 봐야 합니다.

첫째, 표시 환경입니다. 유니코드 박스 드로잉 문자는 고정폭 글꼴과 적절한 유니코드 지원이 필요합니다. 정렬이 깨지면 다이어그램의 가독성도 함께 떨어집니다.²

둘째, 호환성입니다. 모든 터미널과 폰트가 박스 드로잉 문자를 같은 품질로 보여주지는 않습니다. 폭넓은 호환성이 필요하다면 +, -, | 같은 ASCII 기반 대체 출력이 가능한지도 확인해야 합니다. 실제로 Mermaid를 유니코드 텍스트 아트로 렌더링하는 termaid 같은 도구도 고정폭 글꼴을 전제로 설명합니다.³

셋째, 다이어그램의 복잡도입니다. 박스 아트는 픽셀 단위 그래픽이 아닙니다. 복잡한 레이아웃이나 정교한 스타일 표현보다는 구조를 빠르게 전달하는 데 강합니다. 흐름, 상태, 관계처럼 핵심 연결을 읽는 용도에 더 잘 맞습니다.

텍스트 환경까지 다이어그램의 범위가 넓어진다

유니코드에는 Box Drawing 블록의 128개 문자와, 음영 문자를 포함한 Block Elements 블록의 32개 문자가 있습니다.² 이런 문자들은 오래전부터 텍스트 UI에서 그래픽에 가까운 표현을 하기 위해 쓰여 왔습니다. Unicode 13.0에서는 구형 운영체제의 그래픽 문자를 담은 Symbols for Legacy Computing 블록도 추가됐지만, 이 영역은 지원 글꼴이 적다는 한계가 있습니다.²

따라서 실용적인 선택은 명확합니다. 넓은 호환성이 필요하면 기본적인 박스 드로잉 문자 중심으로 쓰고, 더 제한적인 환경에서는 ASCII 대체 표현까지 고려하는 것입니다.

grok-mermaid는 Mermaid 다이어그램의 출력 대상을 브라우저 이미지나 문서 렌더링에만 묶어두지 않습니다. 터미널, 로그, 콘솔, 코드 리뷰처럼 텍스트가 기본인 공간에서도 다이어그램을 읽을 수 있게 합니다.

결론적으로 이 도구의 가치는 “예쁜 그림을 만드는 것”보다 “다이어그램을 텍스트 워크플로 안에 남기는 것”에 있습니다. Mermaid를 문서화 언어로 쓰고 있다면, 이제 출력 대상을 SVG나 PNG뿐 아니라 유니코드 박스 아트까지 넓혀볼 만합니다.

¹Mermaid to Unicode box art

²Box-drawing characters - Wikipedia

³termaid | Mermaid diagrams as Unicode art

⁴mmdc · PyPI