📊 Mermaid 다이어그램 미리보기
Mermaid 문법 입력 시 SVG 즉시 렌더링. flowchart / sequence / class / state / gantt / pie / mindmap / gitGraph / journey 지원. SVG 복사 · SVG/PNG 다운로드 · 테마 전환.
🔒 Mermaid는 CDN에서 로드되며 브라우저 내에서 렌더링. 소스는 서버로 전송되지 않습니다.
📝 Mermaid 입력
👁 미리보기
📖 자주 걸리는 지점
Mermaid 표기를 입력하면 즉시 도형을 그리고 테마를 바꿔 가며 SVG / PNG 로 내보낼 수 있습니다. 그리기는 CDN 에서 읽어들인 Mermaid 가 브라우저 안에서 하며 도형의 소스는 전송되지 않습니다. 검증되는 것은 구문뿐이고 도형의 내용이 옳은지는 보지 않습니다 — 이어지지 않은 화살표도 뜻이 통하지 않는 흐름도 구문만 맞으면 조용히 그려집니다. 그려졌다와 전달된다 사이에는 거리가 있습니다.
| 사례 | 무슨 일이 일어나는가 | 어떻게 하면 되는가 |
|---|---|---|
| 라벨에 괄호나 기호를 넣으면 구문 오류가 난다 | A[처리(1)] 처럼 쓰면 파서는 ) 를 노드 모양의 끝으로 해석해 버려 거기서 깨집니다. 같은 일이 # · : · ; · { · " 에서도 일어납니다. 까다로운 것은 에러가 나는 방식으로 Mermaid 는 몇 번째 줄의 어디가 나쁜지를 거의 알려 주지 않아 도형 전체가 사라지거나 뜻 모를 위치를 가리키는 메시지가 나올 뿐입니다. 50 줄짜리 도형 안에서 한 곳을 찾게 됩니다. |
라벨은 큰따옴표로 감싸세요 — A["처리(1)"] 라고 쓰면 내용은 문자열로 다뤄져 괄호도 기호도 그대로 나옵니다. 라벨 자체에 " 를 넣고 싶을 때는 #quot; 이라는 Mermaid 고유의 엔티티를 쓰고 줄바꿈은 <br/> 입니다. 진단의 요령은 직전에 더한 줄을 의심하는 것 — 돌아가던 도형에 한 줄 더해서 깨졌다면 원인은 거의 확실히 그 줄입니다. 큰 도형을 쓸 때는 5 줄마다 그리기를 확인하세요. 한꺼번에 50 줄 쓴 뒤 깨지면 원인 분리에 시간이 녹습니다. |
| PNG 으로 내보내면 폰트가 바뀐다 · 글자가 사라진다 | PNG 은 그려진 SVG 를 Canvas 에 그린 뒤 내보냅니다. 이 과정에서 SVG 가 참조하는 웹 폰트는 Canvas 쪽에서 해결되지 않고 시스템의 대체 폰트로 떨어집니다. 고정폭으로 맞춰 두었던 표가 어긋나는 것은 이 때문입니다. 나아가 Mermaid 가 HTML 라벨(foreignObject)을 써서 그리고 있는 경우 브라우저에 따라서는 Canvas 에 그린 시점에 라벨이 통째로 공백이 됩니다 — 화면에서는 제대로 보이는데 내보낸 PNG 만 글자가 없는 상태입니다. |
가능한 한 SVG 그대로 쓰세요. GitHub 의 README · Zenn · Notion · 많은 CMS 는 SVG 를 그대로 붙일 수 있고 SVG 라면 확대해도 열화되지 않으며 텍스트로 선택도 됩니다. PNG 가 꼭 필요한 장면(Slack 에 붙이기, SNS 의 카드 이미지)에서는 도형 안의 폰트 지정을 sans-serif 나 system-ui 처럼 확실히 존재하는 것으로 맞추세요. 내보냈으면 반드시 이미지를 열어 내용을 확인하세요 — 공백인 라벨은 내보내기의 성공과 구별되지 않습니다. |
| 도형이 옆으로 너무 늘어나 읽을 수 없다 | flowchart TD(위에서 아래)는 분기가 늘수록 옆으로 퍼지고 LR(왼쪽에서 오른쪽)은 공정이 늘수록 옆으로 늘어납니다. 어느 쪽이나 레이아웃 엔진이 자동으로 배치하므로 이쪽에서 너비를 제어할 수 없습니다. GitHub 의 README 에 붙이면 컨테이너 너비에 맞춰 축소되므로 노드가 15 개를 넘는 언저리부터 글자를 읽을 수 없게 됩니다. 모바일에서는 더 가혹해서 가로 스크롤을 할 수 없는 표시 환경도 많으므로 실질적으로 아무것도 전해지지 않습니다. |
한 장에 밀어 넣는 것을 그만두세요. 읽을 수 없는 도형의 가장 큰 원인은 레이아웃 엔진이 아니라 한 장으로 전부를 설명하려는 것입니다. 전체상을 7 노드 정도로 그리고 각 부분을 별도의 도형으로 나누면 양쪽 다 읽을 수 있게 됩니다. subgraph 로 묶으면 시각적인 덩어리가 생겨 너비도 억제됩니다. 방향은 용도로 고르되 — 절차는 LR, 판단의 분기는 TD 가 읽기 쉬운 경향이 있습니다. 확인은 반드시 붙여 넣을 곳의 실제 너비에서 하세요. 이 페이지의 미리보기는 옆으로 넓으므로 여기서 읽혀도 README 에서는 읽히지 않습니다. |
Mermaid 는 버전에 따라 구문이 바뀝니다. 8 계열에서 11 계열 사이에 graph 는 flowchart 로 대체되었고 gantt 의 날짜 서식이나 classDiagram 의 표기에도 변경이 들어갔습니다. 여기서 쓰고 있는 것은 Mermaid 11 계열이지만 GitHub · GitLab · Notion · 각종 CMS 가 내부에서 쓰는 버전은 제각각이고 게다가 공표되지 않은 경우도 있습니다 — 즉 여기서 제대로 그려져도 붙여 넣는 곳에서 그려지지 않을 가능성이 늘 있습니다. 새로운 구문(mindmap 이나 새로운 모양)을 썼을 때는 특히 붙여 넣는 곳에서의 표시를 반드시 확인하세요. 한 가지 더, Mermaid 의 기본 securityLevel 은 strict 이며 라벨 안의 HTML 이나 클릭 이벤트는 무효화되어 있습니다. 이를 완화하는 설정은 있지만 사용자가 올린 Mermaid 를 그대로 그리는 서비스에서는 절대 완화하지 마세요 — 라벨은 XSS 의 입구가 됩니다.
📖 사용법
-
1
구문 입력왼쪽 에디터에 Mermaid 입력. 샘플 버튼으로 템플릿 로드.
-
2
테마 선택default / dark / forest / neutral 선택.
-
3
내보내기SVG 복사 또는 SVG / PNG 다운로드.
❓ 자주 묻는 질문
지원 다이어그램 타입은?
PNG 다운로드는 어떻게 동작?
Mermaid 소스는 외부 전송됩니까?
🔗 관련 도구
🐛 이 도구에서 문제가 발생했나요?
무료 · 가입 불필요. 재현 절차만이라도 도움이 됩니다. 보고는 운영자에게 직접 전달되어 개선에 사용됩니다.
보고 감사합니다!
운영자에게 전달되었습니다. 개선에 사용됩니다.