Mermaid 다이어그램 임베드 방법
어떤 도구는 일반 텍스트로부터 Mermaid를 직접 그려주고, 다른 도구는 내보낸 이미지가 필요합니다. 어디서 네이티브로 렌더링되는지, 각 플랫폼에 어떻게 임베드하는지, 그리고 도구가 지원하지 않을 때의 대체 방법을 정리했습니다.
- 01
다이어그램 만들기
에디터를 열고 Mermaid를 작성하거나 붙여넣은 다음, 원하는 대로 렌더링되는지 확인하세요.
- 02
소스를 복사하거나 이미지로 내보내기
Mermaid를 네이티브로 렌더링하는 플랫폼에서는 ```mermaid 펜스로 감싼 Markdown 블록을 복사하세요. 그 외의 모든 곳에서는 SVG 또는 PNG로 내보내세요.
- 03
알맞은 위치에 붙여넣기
Mermaid 블록을 네이티브 플랫폼에 붙여넣거나, 내보낸 이미지를 문서, 슬라이드 또는 이메일에 넣으세요. 편집 가능한 상태를 유지하도록 소스는 저장소에 보관하세요.
Mermaid가 렌더링되는 곳 — 플랫폼별 정리
| 플랫폼 | Mermaid 지원 | 임베드 방법 |
|---|---|---|
| GitHub | 네이티브 | 모든 README, Markdown 파일, 이슈, 풀 리퀘스트, 디스커션 또는 wiki에 ```mermaid 펜스 블록을 붙여넣으세요. GitHub가 자동으로 그려줍니다. |
| GitLab | 네이티브 | 동일한 ```mermaid 펜스 블록이 GitLab.com과 자체 관리형 인스턴스의 Markdown, 이슈, 머지 리퀘스트에서 작동합니다. |
| Obsidian | 네이티브 | 아무 노트에나 ```mermaid 코드 블록을 작성하면, Obsidian이 읽기 모드와 라이브 프리뷰 모드에서 렌더링합니다 — 플러그인이 필요 없습니다. |
| Notion | 네이티브 (코드 블록) | /code 블록을 삽입하고 언어를 "Mermaid"로 설정한 다음 소스를 붙여넣고, 블록의 Preview / Split 보기를 사용해 다이어그램을 표시하세요. |
| Confluence | 앱 필요 | Confluence에는 내장 Mermaid 기능이 없습니다. Marketplace 앱(예: Mermaid 매크로)을 설치해 소스를 붙여넣거나, 내보낸 SVG/PNG를 임베드하세요. |
| 내 웹사이트 | 네이티브 (스크립트 추가) | 소스를 class가 "mermaid"인 "pre" 태그에 넣고 CDN에서 mermaid.js를 로드하세요 — 아래 스니펫을 참고하세요. 또는 JavaScript 없이 사용하려면 내보낸 SVG를 임베드하세요. |
| Slack, Google Docs, 이메일, PDF | 이미지 내보내기 | 이들은 Mermaid를 렌더링하지 않습니다. 에디터에서 SVG(어떤 크기에서도 선명함) 또는 PNG로 내보내 그 이미지를 붙여넣으세요. |
플랫폼 기능은 변경될 수 있습니다 — 특히 Notion 프리뷰와 Confluence 앱은 본인 계정에서 직접 확인하세요. "네이티브"는 이미지 업로드 없이 소스로부터 다이어그램이 렌더링됨을 의미합니다.
내 웹사이트에 임베드하기
Mermaid 소스를 class가 "mermaid"인 "pre" 요소에 붙여넣고 CDN에서 렌더러를 로드하세요. 이것이 공식 ESM 임베드 방식입니다 — 그대로 복사하세요:
<pre class="mermaid">
flowchart TD
A[Start] --> B{OK?}
B -->|Yes| C[Ship]
B -->|No| A
</pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>메이저 버전(여기서는 mermaid@11)을 고정해 향후 릴리스가 다이어그램을 예기치 않게 변경하지 못하도록 하세요. JavaScript가 없는 정적 페이지의 경우, 에디터에서 SVG로 내보내 이미지로 참조하세요.
GitHub README, 단계별 가이드
GitHub는 가장 일반적인 대상입니다. 블록이 다이어그램 대신 코드로 표시되는 이유를 포함한 전체 안내는 다음을 참고하세요 GitHub README에 Mermaid 다이어그램을 임베드하는 방법.
먼저 다이어그램을 만드세요: Mermaid 에디터 열기, 준비된 예제.
자주 묻는 질문
어떤 플랫폼이 플러그인 없이 Mermaid를 렌더링하나요?
GitHub, GitLab, Obsidian은 ```mermaid 펜스 블록을 네이티브로 렌더링합니다. Notion은 Mermaid 언어로 설정한 코드 블록 안에서 프리뷰 보기로 렌더링합니다. Slack, Google Docs, 이메일 등 대부분의 다른 도구는 대신 내보낸 SVG 또는 PNG 이미지가 필요합니다.
Notion에 Mermaid 다이어그램을 어떻게 임베드하나요?
코드 블록을 추가하고(/code 입력), 언어를 "Mermaid"로 변경한 다음, 다이어그램 소스를 붙여넣으세요. Notion은 블록에 다이어그램을 렌더링하는 Preview / Split 토글을 표시합니다. 정적 사본이 필요하면 에디터에서 이미지로 내보내 그것을 임베드하세요.
내 웹사이트에 Mermaid 다이어그램을 어떻게 표시하나요?
소스를 class가 "mermaid"인 "pre" 요소 안에 넣고 mermaid.initialize({ startOnLoad: true })와 함께 CDN에서 mermaid.js를 로드하세요. 이 페이지의 스니펫이 완전히 작동하는 예제입니다. JavaScript를 전혀 포함하지 않으려면 SVG로 내보내 이미지로 사용하세요.
소스를 임베드해야 하나요, 아니면 내보낸 이미지를 임베드해야 하나요?
플랫폼이 Mermaid를 렌더링하는 곳(GitHub, GitLab, Obsidian, 내 사이트)에서는 소스를 임베드하세요 — 버전 관리에서 편집 및 diff가 가능한 상태로 유지됩니다. 그렇지 않은 곳에서는 SVG 또는 PNG로 내보내세요. SVG는 흐려지지 않고 확대되며, PNG는 슬라이드에 적합합니다.
Confluence는 Mermaid를 지원하나요?
기본적으로는 지원하지 않습니다. Mermaid 매크로를 추가하는 Marketplace 앱이 필요하거나, 내보낸 SVG/PNG 이미지를 붙여넣을 수 있습니다. 설치가 허용된 앱은 Confluence 관리자에게 확인하세요.