Pele: Mermaid 다이어그램을 가볍고 빠르게 SVG로 그리는 라이브러리

문서나 블로그에 시스템 흐름을 설명할 때 Mermaid를 자주 사용합니다. A --> B처럼 텍스트로 관계를 적으면 도형과 화살표로 바꿔 주므로 코드와 함께 버전을 관리하기도 편합니다. 다이어그램이 많은 문서 도구나 웹페이지에서는 이 텍스트를 실제 화면으로 그리는 과정의 속도와 스타일도 신경 쓰게 됩니다.

Pele 는 Mermaid 문법으로 작성한 다이어그램을 SVG로 그려 주는 오픈소스 라이브러리입니다. 원문 Threads 게시물 은 이 라이브러리의 속도와 크기, 테마 적용 방식을 소개합니다. 아래에서는 공식 저장소 와 문서를 함께 참고해 무엇을 바꾸는 도구인지, 기존 Mermaid 화면에 적용할 때 무엇을 확인할지 정리했습니다.

Mermaid 문법을 읽어 SVG를 만드는 도구

Mermaid를 사용할 때는 다이어그램을 설명하는 텍스트와 그 텍스트를 화면에 그리는 렌더러를 구분하면 이해하기 쉽습니다. 아래는 순서도를 설명하는 Mermaid 텍스트입니다.

flowchart LR
  A[요청 접수] --> B{검토 필요?}
  B -->|예| C[담당자 검토]
  B -->|아니오| D[처리 완료]
  C --> D

flowchart LR은 왼쪽에서 오른쪽으로 흐르는 순서도를 뜻합니다. 대괄호는 일반 노드, 중괄호는 판단 지점, 화살표는 노드 사이의 연결을 나타냅니다. 이 텍스트를 렌더러가 읽으면 요청 접수에서 검토 여부를 거쳐 완료로 이어지는 그림이 나옵니다.

Pele는 이런 텍스트를 입력받아 SVG 를 만듭니다. SVG는 도형과 선, 글자를 기술하는 벡터 이미지 형식입니다. 웹페이지에 넣거나 확대해 볼 수 있으며 Pele는 색상과 글꼴을 CSS로 조정하는 방법도 제공합니다.

Obsidian의 GitHub 조직에서 공개한 프로젝트이고 패키지의 작성자는 kepano로 표시되어 있습니다. 공식 사이트는 Obsidian을 위해 개발한 라이브러리라고 소개합니다. 다만 라이브러리를 웹사이트에 도입하는 일과 자신이 사용하는 Obsidian 버전의 렌더러를 바꾸는 일은 별도이므로, 앱 적용 여부는 해당 버전의 안내를 확인해야 합니다.

속도·패키지 크기·테마에서 무엇을 강조할까

공식 사이트 는 실행 시 필요한 외부 패키지가 없고 Mermaid.js보다 작은 번들과 빠른 렌더링을 제공한다고 설명합니다. 여기서 외부 패키지가 없다는 말은 Pele의 런타임 의존성을 뜻합니다. 웹 애플리케이션 전체에 다른 라이브러리가 필요 없다는 의미는 아닙니다.

사이트의 자체 비교에서는 gzip 기준 번들 크기를 Pele 230kB, Mermaid.js 1.6MB로 제시하며 렌더링 속도는 최대 500배 빠르다고 안내합니다. 이 수치는 프로젝트가 공개한 비교 결과입니다. 모든 다이어그램에서 같은 배율로 빨라지거나 웹페이지 전체의 로딩 시간이 그만큼 줄어든다는 뜻으로 읽으면 안 됩니다.

실제 적용에서는 자신이 쓰는 다이어그램의 종류와 크기, 한 페이지의 개수, 글꼴 로딩과 브라우저 환경을 함께 확인하는 편이 좋습니다. 단순한 순서도 하나와 긴 시퀀스 다이어그램 여러 개는 렌더링에 필요한 작업량이 다르기 때문입니다.

테마는 CSS 변수로 설정합니다. 배경색·글자색·선 색상을 사이트의 스타일과 연결할 수 있고 색상 테마를 바꿀 때 다이어그램을 다시 그리지 않아도 됩니다. 문서 사이트의 밝은 화면과 어두운 화면에 같은 다이어그램을 맞춰 넣고 싶을 때 살펴볼 만한 부분입니다.

먼저 예제로 동작 확인하기

처음에는 공식 Playground 에서 기존 Mermaid 텍스트를 붙여 넣고 결과를 확인하면 됩니다. 별도 프로젝트에 설치하기 전에 문법을 읽을 수 있는지, 노드와 화살표 배치가 원하는 방식인지 살펴볼 수 있습니다.

웹 프로젝트에 적용한다면 npm으로 설치할 수 있습니다.

npm install pele

기본 API는 텍스트를 받아 SVG 문자열을 반환하는 render()입니다. 아래 코드는 npm 패키지를 불러올 수 있는 JavaScript 모듈 환경을 가정합니다. HTML 파일에 그대로 붙여 넣는 예제와는 실행 환경이 다릅니다.

import { render } from 'pele';

const source = `flowchart LR
  A[요청 접수] --> B[담당자 검토]
  B --> C[처리 완료]`;

const { svg } = render(source);
document.querySelector('#diagram').innerHTML = svg;

페이지에는 결과를 넣을 요소가 있어야 합니다.

<div id="diagram"></div>

이 예제에서 source는 다이어그램의 원본 텍스트이고 svg는 렌더링한 결과입니다. 마지막 줄은 그 SVG를 diagram이라는 ID의 요소에 넣습니다. 이 코드를 실행하기 전에 해당 요소가 만들어져 있어야 합니다.

컨테이너 너비에 따라 배치를 조정하는 화면이라면 API 문서 의 mount()도 확인할 수 있습니다.

import { mount } from 'pele';

const container = document.querySelector('#diagram');
const source = `flowchart LR
  A[작성] --> B[검토] --> C[게시]`;

mount(container, source);

render()는 SVG 결과가 필요한 경우에, mount()는 브라우저의 요소에 연결해 너비 변화에 대응하는 경우에 검토하면 됩니다. 문서에서는 두 API 모두 동기적으로 동작한다고 설명하며 필요한 다이어그램 종류를 나중에 불러오는 별도 진입점도 제공합니다.

사이트의 밝은 화면과 어두운 화면에 맞추기

테마 문서 에서는 .pele 클래스나 다이어그램을 감싼 요소에 CSS 변수를 지정하도록 안내합니다.

.pele {
  --pele-bg: #ffffff;
  --pele-fg: #1f1f1f;
  --pele-line: #6e6e6e;
  --pele-surface: #f3f3f3;
  --pele-border: #8a8a8a;
}

@media (prefers-color-scheme: dark) {
  .pele {
    --pele-bg: #1f1f1f;
    --pele-fg: #eeeeee;
    --pele-line: #aaaaaa;
    --pele-surface: #303030;
    --pele-border: #777777;
  }
}

--pele-bg는 배경, --pele-fg는 글자, --pele-line은 연결선의 색상입니다. 위 코드는 운영체제의 화면 모드에 따라 색상을 바꾸는 예제입니다. 사이트가 자체 테마 버튼을 쓴다면 해당 사이트의 테마 클래스나 속성에 맞춰 선택자를 바꿔야 합니다.

색상 변경과 글꼴 변경은 구분해서 보는 편이 좋습니다. 글꼴을 바꾸면 글자의 폭이 달라져 노드 크기를 다시 계산할 필요가 있습니다. 또 다이어그램 안에서 특정 색상을 직접 지정했다면 그 값이 테마 색상보다 우선할 수 있습니다.

Mermaid와 호환돼도 화면이 같지는 않습니다

호환성 문서 는 Mermaid 12.1.0에 기본으로 포함된 모든 다이어그램 유형을 지원한다고 안내합니다. 순서도, 시퀀스, 클래스, 상태, ERD, 간트 차트 등 여러 종류를 같은 문법으로 작성할 수 있습니다.

다만 Pele는 자체 배치 엔진과 시각 스타일을 사용합니다. 같은 Mermaid 텍스트라도 노드 위치와 간격, 연결선 경로가 달라질 수 있습니다. 문법을 읽는다는 것과 기존 화면을 같은 모습으로 재현한다는 것은 구분해야 합니다.

공식 문서는 외부 Mermaid 플러그인, 임의의 HTML 라벨, click 구문의 JavaScript 콜백을 그대로 지원하지 않는다고 설명합니다. 기존 문서에서 이런 기능을 사용했다면 렌더러를 교체하기 전에 별도로 점검할 필요가 있습니다.

어떤 프로젝트에서 검토하면 좋을까

이미 Mermaid로 문서를 관리하면서 다이어그램 표시 속도나 번들 크기를 줄이고 싶다면 Pele를 후보로 검토할 만합니다. 문서 사이트와 블로그, 제품 설명 페이지처럼 사이트 테마에 다이어그램 색상을 맞춰야 하는 곳에서도 장점이 있는지 확인해 볼 수 있습니다.

처음부터 전체 렌더러를 바꾸기보다 대표 다이어그램 몇 개를 골라 비교하는 편이 좋습니다. 짧은 순서도뿐 아니라 노드가 많은 구조도, 긴 한글 라벨, 좁은 화면에서 읽을 시퀀스 다이어그램을 함께 확인하면 교체 범위를 정하기 쉽습니다. 여기서 제시한 코드는 API 사용 예시이며 웹사이트 전체의 성능 개선을 측정한 결과는 아닙니다.

Pele의 라이선스는 MIT입니다. 직접 적용하기 전에는 공식 저장소 와 Playground에서 자신의 Mermaid 문서가 어떻게 그려지는지 확인하는 것부터 시작하면 됩니다.

대표 이미지: Pele 공식 저장소 의 프로젝트 이미지.