모바일에서 읽히지 않던 문서 다이어그램을 Mermaid에서 Pele로 바꾼 과정

이 글에서 얻을 수 있는 것

• Mermaid 다이어그램이 좁은 화면에서 통째로 줄어들어 읽히지 않는 문제를, Pele가 레이아웃을 다시 계산하는 방식으로 푸는 과정입니다. 375px 화면의 변경 전후 캡처를 함께 보여 줍니다.
• 렌더러를 바꾸기 전에 해 볼 일입니다. 다이어그램의 자연 너비를 브라우저에서 재서 좁은 화면에서 문제가 될 것을 숫자로 가려내는 방법과, 다이어그램 코드에 박힌 색 지정(classDef)을 걷어내고 CSS로 옮겨 다크 모드에 대응하는 방법을 다룹니다.

이런 분께 맞습니다: Mermaid 다이어그램이 많은 마크다운 기반 문서 사이트를 운영하면서 모바일 가독성이 걱정되는 경우입니다.

맞지 않는 경우: 빌드 단계에서 SVG를 미리 그려 두어야 하는 경우입니다. 너비에 맞춘 레이아웃은 브라우저에서만 동작했습니다.

도브러너 문서 사이트(docs.doverunner.com)에는 설명을 돕기 위해 넣은 Mermaid 다이어그램이 영어와 한국어를 합쳐 84개 있습니다. 라이선스 발급 흐름이나 워터마킹 워크플로처럼 단계가 많은 내용은 글보다 그림이 빠르게 전달되기 때문입니다. 그런데 화면이 좁아지면 Mermaid는 다이어그램 전체를 비율대로 줄여서 보여 주고, 가로로 긴 그림은 글자가 읽을 수 없는 크기까지 작아졌습니다. 휴대폰으로 문서를 열면 설명의 핵심인 그림이 오히려 읽을 수 없는 상태였습니다.

Pele가 풀어 주는 문제

Pele는 Obsidian용으로 개발된 오픈소스(MIT) 라이브러리로, Mermaid 문법으로 쓴 다이어그램을 자체 레이아웃으로 SVG로 그려 줍니다. 제가 눈여겨본 점은 컨테이너 너비에 맞춰 레이아웃을 다시 계산한다는 것입니다. Mermaid는 완성된 그림을 줄이지만, Pele는 컨테이너가 기본값 640px보다 좁아지면 가로로 넓은 플로차트를 세로 배치로 바꾸기도 합니다. Pele 사이트는 번들 크기가 gzip 기준 230kB로 Mermaid.js의 1.6MB보다 작다고 소개하는데, 이 수치는 제가 직접 잰 값이 아닙니다.

Pele 사이트를 찾은 것은 저였고, 검토는 Claude Code에게 맡겼습니다. 도입 전에 확인할 것은 두 가지였습니다. 우리 문서의 다이어그램이 문법 차이 때문에 깨지지 않는지, 그리고 정말 좁은 화면에서 읽기 좋아지는지입니다.

검증은 실제 문서로 했습니다

먼저 Claude Code가 영어 문서의 다이어그램 42개를 Node에서 Pele로 렌더링해 보았고 오류 없이 모두 그려졌습니다. 이어서 세 페이지에 파일럿을 적용했습니다. 코드 블록에 mermaid pele를 지정한 다이어그램만 Pele로 그리고 나머지는 기존 방식을 유지하는 구조라, 문제가 생기면 쉽게 되돌릴 수 있었습니다.

375px 화면에서 운영 사이트와 나란히 비교했습니다. CloudFront 임베더 안내의 시퀀스 다이어그램은 운영 사이트에서 작은 상자 안에 글자가 깨알처럼 들어가 있었는데, Pele로 그리자 본문 폭을 채우고 글자도 읽을 수 있었습니다. 가로에서 세로로 바뀌는 동작은 플로차트에 해당하는 설명이고, 이 캡처는 시퀀스 다이어그램이 본문 폭에 맞춰 그려지는 모습입니다.

변경 전 (Mermaid, 운영 사이트)	변경 후 (Pele)

여기서 예상과 다른 점이 하나 있었습니다. 처음에는 빌드할 때 SVG를 미리 만들어 두면 된다고 생각했는데, 컨테이너 너비를 알아야 레이아웃을 바꿀 수 있어서 브라우저에서 mount()(요소 안에 다이어그램을 그려 주는 함수)로 그려야 했습니다. Node에서 render()로 SVG를 만들 수는 있지만, 이때는 브라우저의 실제 글꼴을 쓰지 못하고 Pele에 내장된 글자 폭 추정치로 크기를 계산하기 때문에 실제와 크기가 조금 다른 고정 레이아웃이 나옵니다. 브라우저의 mount()는 CSS의 글꼴로 글자 폭을 재고 컨테이너 너비가 바뀔 때마다 다시 그립니다. 그래서 마크다운을 변환하는 remark 플러그인은 코드 블록을 <pre>로 바꿔 두기만 하고, 작은 스크립트가 다이어그램이 있는 페이지에서만 Pele를 불러와 그리도록 했습니다.

다크 모드에서 드러난 색상 문제

파일럿이 잘 되자 모든 코드 블록을 Pele로 그리도록 바꾸고 84개 전체를 375px 브라우저에서 그려 가로로 넘치지 않는지 확인했는데, 가장 손이 많이 간 부분은 색상이었습니다. 기존 다이어그램에는 classDef로 단계, 선택, 판단, 실행 노드마다 연한 파랑, 주황, 분홍, 초록 배경을 직접 지정해 두었습니다(영어와 한국어를 합쳐 24줄). Pele는 이 지정을 노드의 인라인 스타일로 그대로 적용합니다. 밝은 배경에 맞춘 색이라 다크 모드에서는 글자가 어두운 채로 밝은 상자 안에 박혀 어색해졌습니다.

그래서 다이어그램 안의 classDef, style, %%{init}%% 지정을 렌더링 직전에 제거하고, :::step 같은 클래스 이름만 남겨 CSS에서 색을 입히는 방식으로 바꿨습니다. 라이트 모드와 다크 모드의 팔레트는 따로 만들었습니다. 원본 Mermaid 코드는 그대로 두었기 때문에 문서를 고치는 사람이 새로 배울 것은 없습니다.

얻은 것

84개 다이어그램이 모두 Pele로 그려지고 375px에서도 가로 스크롤이 생기지 않으며, 라이트 모드와 다크 모드에 같은 색 체계의 팔레트를 적용했습니다. astro-mermaid와 mermaid 의존성도 빠졌습니다. 마크다운 사본(.md)에는 다이어그램이 Mermaid 코드 블록 그대로 남기 때문에, 문서를 읽는 AI 에이전트가 그림을 텍스트로 이해할 수 있다는 점도 그대로입니다.

비슷한 전환을 준비한다면

다이어그램 렌더러를 바꾸려는 분께 권하고 싶은 순서는 세 가지입니다.

1. 자연 너비부터 재 보세요. 어떤 다이어그램이 좁은 화면에서 문제인지는 렌더링한 SVG의 viewBox(그림이 차지하는 좌표 영역) 너비를 본문 폭과 비교하면 숫자로 나옵니다. 측정은 브라우저에서 mount()로 하는 것이 정확합니다. 저는 처음에 Node에서 render()로 쟀는데 글자 폭 추정치 때문에 실제보다 8% 정도 작게 나왔고, 브라우저에서 다시 재서 숫자를 바로잡았습니다.
2. 색은 다이어그램 안이 아니라 CSS에 두세요. 다크 모드를 지원하려면 classDef처럼 코드에 박힌 색을 걷어내고 클래스 이름만 남기는 편이 안전합니다.
3. 렌더러를 바꾼 뒤에도 다이어그램 원본을 점검하세요. 가로로 너무 긴 그림은 어느 렌더러에서나 읽기 어렵습니다. 방향을 바꾸거나 라벨을 줄이는 수정이 렌더러 설정을 바꾸는 것보다 나을 수 있습니다.

마치며

이번 전환에서 효과가 컸던 것은 실제 문서 세 페이지로 먼저 시험한 파일럿과, 브라우저에서 잰 숫자였습니다. 색상은 다이어그램 안이 아니라 CSS에서 관리하게 되었으니, 앞으로 문서를 고치는 분은 Mermaid 코드만 보시면 됩니다.

참고 자료

• Pele 공식 사이트, 호환성 문서
• obsidianmd/pele GitHub 저장소