10월 17~18일 Hacker News에서 눈에 띈 프로젝트가 있습니다. 이름은 Pele입니다. 한 줄로 말하면 "Mermaid 다이어그램을 CSS로 꾸미는 경량 SVG 렌더러"입니다.
왜 이게 지금 화제일까요. 최근 LLM은 다이어그램을 설명할 때 Mermaid 문법을 아주 잘 뱉습니다. 문제는 그 다음입니다. 그 텍스트를 웹사이트나 문서에 넣으려면 렌더러가 필요합니다. 기존 Mermaid.js는 강력하지만 무겁고, 테마를 맞추기 어렵고, 좁은 화면에서 다이어그램을 축소해 버립니다.
Pele는 이 세 가지를 정면으로 겨냥합니다. 만든 사람은 Obsidian의 kepano(Steph Ango)이고, 이름은 화산의 여신 Pele에서 따왔습니다.
무엇인가
Pele (MIT, github.com/obsidianmd/pele)
- 형태 : Mermaid 문법 → SVG 렌더러
- 의존성 : 런타임 의존성 0개
- 방식 : 동기(synchronous) 렌더링
- 테마 : CSS 변수로 색·폰트 지정
(색을 바꿔도 다시 렌더링할 필요가 없다)
- 문법 : Mermaid 12.1.0에 내장된 모든 다이어그램 타입 지원
- 검증 : Mermaid의 파서 스펙과 대조 테스트 + 차분 퍼징
- 개발 배경 : Obsidian에서 다이어그램을 빠르고 테마에 맞게
그리기 위해 만들었다
사용법은 두 줄입니다.
npm install pele
import { render } from 'pele';
const { svg } = render(`flowchart LR
A[Mermaid text] --> B[SVG]`);
document.querySelector('#diagram').innerHTML = svg;
mount()를 쓰면 브라우저에서 요소에 직접 그리고, CSS에서 폰트를 읽고, 컨테이너 너비에 맞춰 레이아웃을 조정합니다. 번들이 부담되면 pele/core에 필요한 다이어그램 타입만 등록하거나, pele/lazy의 renderAsync()로 지연 로딩할 수 있습니다. CDN 전역 빌드도 있습니다.
공개된 비교표
프로젝트가 공개한 비교표는 이렇습니다.
| 항목 | Pele | Mermaid.js |
|---|---|---|
| 번들 크기 (gzip) | 230 kB | 1.6 MB |
| 렌더링 시간 | 0.05~0.3 ms | 6~82 ms |
| 직접 의존성 | 0개 | 23개 |
| 작은 화면 | 레이아웃을 적응시킴 | 다이어그램을 축소 |
| 테마 | CSS 변수 | 테마 설정 |
요약하면 6배 작고, 최대 500배 빠릅니다. 표의 숫자를 그대로 인용했지만, 마지막 열은 짚고 넘어가야 합니다. 자체 벤치마크라는 점입니다. 렌더러 저장소에는 npm run bench가 있어 직접 재현할 수 있지만, 다이어그램의 종류와 크기에 따라 체감 차이는 달라집니다. "모든 다이어그램이 항상 500배 빠르다"로 읽으면 안 됩니다.
그래도 두 번째 행은 실무적으로 의미가 있습니다. Mermaid.js의 6~82ms는 렌더링이 UI 스레드를 붙잡는 시간입니다. 다이어그램이 여러 개인 문서에서는 이 차이가 누적되어 체감됩니다.
왜 CSS 변수인가
Pele의 가장 실용적인 특징은 테마 방식입니다. 색을 다시 그리지 않고 바꿀 수 있습니다.
[Pele의 테마 방식]
.pele {
--pele-bg: #fffcf0;
--pele-fg: #100f0f;
--pele-line: #100f0f;
--pele-surface: #f2f0e5;
--pele-accent: #205ea6;
--pele-font: sans-serif;
--pele-radius: 4px;
}
차트는 --pele-series-1 ~ --pele-series-8 사용
+ 다크 모드 / 라이트 모드 전환 시
렌더링을 다시 하지 않고 색만 바뀐다
이건 단순한 편의가 아닙니다. 사이트 테마가 바뀔 때 다이어그램을 다시 그리지 않아도 되고, 서버에서 렌더링한 SVG를 캐시한 채 색만 CSS로 관리할 수 있습니다. Mermaid의 테마 설정(themeVariables)은 적용되지 않으니, 마이그레이션할 때는 이 차이를 염두에 둬야 합니다.
전: 호환성과 한계
새 렌더러에는 새 렌더러의 제약이 있습니다. 공식 문서가 정리한 차이입니다.
[레이아웃과 모양]
- Pele는 자체 레이아웃 엔진을 쓴다
→ 노드 위치·간격·엣지 경로가 Mermaid와 다르다
- Mermaid의 테마와 themeVariables 색은 적용되지 않는다
[크기]
- 좁은 컨테이너에서는 다이어그램이 축소된다
- maxWidth를 넘기면 레이아웃이 적응한다
(예: 넓은 flowchart가 세로 배치로 바뀐다)
- responsive: false 로 고정 픽셀 크기 지정
[제한]
- 소스 길이, SVG 출력 크기, flowchart·agentflow의 엣지 수에 제한
- 라벨은 SVG 텍스트 (줄바꿈·굵게·기울임 지원)
→ 임의의 HTML 라벨은 지원하지 않는다
- click으로 링크를 여는 것은 지원, JS 콜백은 무시된다
- ZenUML 등 외부 Mermaid 플러그인은 미지원
→ supports()로 특정 타입 지원 여부를 확인
보안도 문서화되어 있습니다. 신뢰할 수 없는 다이어그램을 다룰 때를 대비해 텍스트를 이스케이프하고, 링크와 스타일을 필터링하며, 소스와 출력 크기를 제한합니다. 즉 "아무 Mermaid나 그냥 넣으면 된다"가 아니라, 출처가 불분명한 다이어그램에는 제한을 두고 써야 합니다.
결론: AI가 그린 다이어그램을 가볍게 얹는 법
브리핑의 액션을 실험으로 옮기면 이렇습니다.
[같은 Mermaid를 두 렌더러로 비교해 보기]
1. 준비
[ ] 같은 Mermaid 코드 한 벌을 만든다
[ ] 한쪽은 Mermaid.js, 한쪽은 Pele로 렌더링
2. 화면에서 볼 것
[ ] 렌더링 속도 (특히 다이어그램이 여러 개일 때)
[ ] 가독성 (라벨, 배치, 색 대비)
[ ] 호환성 (내가 쓰는 다이어그램 타입이 다 되는가)
3. 통합에서 볼 것
[ ] 번들 크기 (gzip 230KB vs 1.6MB)
[ ] 사이트 테마 전환 시 색이 따라오는가
[ ] 좁은 화면에서 레이아웃이 어떻게 변하는가
4. 판단
[ ] 밀도 높은 문서·게시판이면 Pele가 유리
[ ] 지원하지 않는 다이어그램 타입이 있으면 폴백 필요
핵심 문장은 이렇습니다.
AI가 만들어 준 그림을 웹에 얹는 일은
이제 렌더러 선택의 문제다.
LLM이 Mermaid를 잘 뱉는다는 사실은 이미 상수입니다. 변수는 그 텍스트를 얼마나 가볍게, 얼마나 테마에 맞게, 얼마나 안전하게 그리느냐입니다. 같은 Mermaid 코드를 두 렌더러에 넣고 실제 화면에서 비교해 보면, 어느 쪽이 내 문서에 맞는지 금방 판단이 섭니다. 웹에 다이어그램을 통합하는 감각은 AI 바이브코딩 웹 개발에서 다뤘고, 생성형 AI로 시각 자료를 만드는 흐름은 생성형 AI 콘텐츠 입문에서 이어 볼 수 있습니다.
함께 읽으면 좋은 글
참고 자료
이 주제를 직접 따라가며 배우고 싶다면
렌더러를 골라 붙이고, 테마를 맞추고, 좁은 화면까지 챙기는 일은 결국 웹을 만들어 보는 경험에서 빨리 늘어납니다. 아이디어를 웹으로 빠르게 꺼내는 흐름을 직접 해보면, 어떤 도구를 어디에 붙일지 감이 옵니다.