Mermaid 다이어그램을 터미널에서 읽는 법: mermaid-ascii

서버나 SSH 세션처럼 이미지를 표시하기 어려운 환경에서는 Mermaid 다이어그램이 코드로만 보이기 쉽다. mermaid-ascii는 Mermaid 문법을 ASCII 또는 유니코드 박스 문자 아트로 변환해, 다이어그램의 구조를 터미널에서도 읽을 수 있게 한다.¹

플로차트의 레이블 간선, 서브그래프, 색상 정의와 시퀀스 다이어그램의 노트 및 일부 제어 흐름 프래그먼트를 지원한다. 패딩과 출력 방식도 조정할 수 있다. 웹 버전은 Go 라이브러리를 WebAssembly로 컴파일해 브라우저에서 실행하므로 별도 설치 없이 시험할 수 있다.¹²

텍스트 출력이 주는 실용성

변환 결과는 이미지가 아니라 복사하고 검색할 수 있는 텍스트다. 따라서 SSH 세션, CLI 문서 뷰어, 로그, AI 코딩 도구처럼 이미지 처리가 불편한 환경에 적합하다.

기존 마크다운 도구와 연결하는 방식도 비교적 단순하다. Glow 연동 사례에서는 Mermaid 코드 블록을 임시 파일에 저장한 뒤 mermaid-ascii -f로 변환하고, 결과를 일반 코드 블록으로 감싸 터미널에 표시한다. 이 래퍼는 파일 입력과 페이저 모드, 표준입력 파이프도 지원한다.³

Mermaid 전체 호환 도구는 아니다

도입 여부를 판단할 때는 기능 목록보다 팀이 실제로 사용하는 다이어그램이 렌더링되는지를 확인해야 한다.

한 기업의 실제 RFC에서 수집한 Mermaid 다이어그램 593개를 시험한 결과, 191개인 약 32%가 렌더링됐다. 유형별로는 플로차트·그래프가 216개 중 147개였지만, 시퀀스 다이어그램은 282개 중 44개에 그쳤다.⁴

해당 테스트 당시 ER 다이어그램 77개와 stateDiagram-v2 10개는 지원되지 않았다. 첫 줄의 공백과 방향 지정 누락은 플로차트·그래프 인식 실패의 주요 원인으로 보고됐다. 시퀀스 다이어그램에서는 일부 화살표와 활성화·비활성화, box, par, critical, break, rect 구문이 지원 확대 대상으로 제시됐다.⁴

이 수치는 모든 문서에서의 성공률을 뜻하지는 않는다. 다만 Mermaid 문법을 폭넓게 사용하는 조직이라면, 현재 지원 범위만 보고 일괄 적용해서는 안 된다는 점을 보여준다.

도입 전에는 실제 문서로 검증해야 한다

mermaid-ascii는 Mermaid 렌더러의 완전한 대체재라기보다 터미널용 보조 렌더러로 보는 편이 적절하다. 적용 전에는 팀 문서에서 자주 사용하는 플로차트와 시퀀스 다이어그램을 대표 표본으로 골라 변환 결과를 확인하는 것이 좋다. 렌더링에 실패하면 원본 Mermaid 코드를 그대로 보여주는 대체 경로도 마련해야 한다.

단순한 플로차트가 중심이라면 터미널 문서의 가독성을 빠르게 높일 수 있다. 반대로 복잡한 시퀀스·ER·상태 다이어그램이 많다면 사용 중인 문법과 현재 버전의 지원 범위를 먼저 검증해야 한다. 핵심은 Mermaid를 모두 대체하는 것이 아니라, 이미지가 없는 환경에서도 필요한 구조를 얼마나 안정적으로 전달할 수 있는지 판단하는 데 있다.

¹GitHub - AlexanderGrooff/mermaid-ascii

²Mermaid to ASCII art (mermaid-ascii)

³glowm - Glow wrapper with mermaid-ascii support

⁴Tracking: broaden mermaid coverage to render real-world RFC diagrams