Mermaid 사용자 지정 SVG 아이콘: 자신의 그림 등록하기

Mermaid에서 자신의 SVG 아이콘을 쓰려면 그리기 콘텐츠와 좌표 크기를 Iconify 아이콘 세트에 넣고 mermaid.registerIconPacks()를 호출한 뒤 다이어그램에서 등록 이름을 참조하세요. SVG 파일명만으로 아이콘이 등록되지는 않습니다.

이 작업 흐름은 Mermaid JavaScript를 제어할 수 있는 페이지나 앱에 적합합니다. 호스팅된 Markdown 편집기는 다이어그램 텍스트만 제공할 수 있으므로 아이콘 모음 전체를 준비하기 전에 통합 옵션을 확인하세요. 단순한 픽토그램 하나와 연결선 하나로 시작하세요. 다이어그램 레이블은 그림과 별도로 유지되도록 Mermaid에 두세요.

팩을 등록할 위치 확인하기

Mermaid 등록 API는 아이콘 세트를 직접 받거나 세트를 반환하는 로더를 받습니다. 등록한 name이 다이어그램에서 쓰는 접두사가 됩니다. 이 예제는 팩이 garden, 아이콘이 leaf이므로 참조는 garden:leaf입니다.

등록은 렌더러를 준비하는 JavaScript에 넣습니다. Mermaid 코드 블록에 그 JavaScript를 붙이는 것은 같은 작업이 아닙니다. 게시 플랫폼에서 렌더러를 구성할 수 없다면 지원 아이콘 세트를 사용하거나 직접 제어하는 작업 흐름에서 다이어그램을 렌더링해 내보낸 결과를 넣으세요. 이후 편집을 위해 Mermaid 소스를 결과와 함께 유지하세요.

이 안내는 로컬 HTTP로 제공하는 일반 HTML 페이지를 사용합니다. CDN에서 고정 Mermaid 12.0.0 모듈을 불러오므로 네트워크 접근이 필요합니다. 운영 앱은 선택한 Mermaid 버전을 번들에 넣을 수 있습니다. 예제를 적용하기 전에 해당 버전과 호스트 콘텐츠 보안 정책을 테스트하세요.

SVG 그리기 좌표 보존하기

테스트에 사용한 직접 만든 잎입니다. 그림을 따로 확인하려면 leaf.svg로 저장하세요.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 24">
  <path fill="#167c72"
    d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>
  <path fill="none" stroke="#d7f1ca" stroke-width="1.8"
    d="M5 18L23 7"/>
</svg>

Iconify의 body 필드는 바깥 <svg> 요소 없이 SVG 루트 내부 콘텐츠를 담습니다. 좌표 사각형은 left, top, width, height로 따로 전달합니다. 이 파일의 원점은 0이고 크기는 32 × 24입니다.

렌더링 CSS 크기를 대신 복사하지 마세요. 64픽셀로 표시되는 파일도 viewBox는 0 0 32 24일 수 있습니다. 경로는 후자의 좌표계로 그려졌습니다. 원점이 0이 아니면 해당 left, top도 유지하거나 패키징 전에 의도적으로 그림을 원점 0의 캔버스로 이동하세요.

Iconify 세트는 prefix와 icons 객체를 포함합니다. 각 아이콘 키가 그림 이름입니다. 여기서는 크기를 명시하는 것이 유용합니다. 아이콘과 세트 모두 크기를 제공하지 않으면 Iconify의 너비·높이 기본값은 16입니다. 더 큰 캔버스에 그린 그림이 잘릴 수 있습니다.

픽토그램 세트를 준비한다면 외곽선, 여백과 시각적 무게를 먼저 완성하세요. SVG UI 키트 준비 가이드는 원본 그림에 관한 결정을 다룹니다. 아이콘을 패키징해도 실루엣이 개선되지는 않습니다.

완전한 두 노드 예제 실행하기

새 폴더에 다음을 index.html로 저장하세요. Python이 있으면 해당 폴더에서 python3 -m http.server 8000을 실행하고 브라우저에서 http://localhost:8000을 여세요.

<!doctype html>
<meta charset="utf-8">
<title>Custom Mermaid leaf icon</title>
<div id="diagram"></div>
 
<script type="module">
import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
 
const icons = {
  prefix: 'garden',
  icons: {
    leaf: {
      width: 32,
      height: 24,
      body: '<path fill="#167c72" d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>' +
        '<path fill="none" stroke="#d7f1ca" stroke-width="1.8" d="M5 18L23 7"/>'
    }
  }
};
 
mermaid.registerIconPacks([{ name: 'garden', icons }]);
mermaid.initialize({ startOnLoad: false, theme: 'neutral' });
 
const definition = `architecture-beta
  service source(garden:leaf)[Source]
  service library(database)[Library]
  source:R --> L:library`;
 
const { svg } = await mermaid.render('garden-diagram', definition);
document.querySelector('#diagram').innerHTML = svg;
</script>

Source에서 Library로 연결된 잎과 데이터베이스 심볼이 보여야 합니다. 잎은 등록한 팩에서 나오고 database는 Mermaid의 기본 아키텍처 아이콘입니다. 아키텍처 문법 참고 문서는 괄호 안 아이콘 이름, 대괄호 안 레이블과 간선에 쓰는 서비스 측면을 설명합니다.

예제는 자동 렌더링을 끄고 등록 후 render()를 한 번 명시적으로 호출합니다. 테스트 중 순서를 분명히 합니다. 기존 사이트에 통합할 때는 등록과 렌더링 호출이 같은 Mermaid 인스턴스를 쓰도록 하세요.

이 예제는 직접 작성한 작고 신뢰할 수 있는 그림입니다. 큰 아이콘 모음에서는 모든 SVG 내보내기를 추가 작업 없이 경로 문자열로 줄일 수 있다고 가정하지 말고 Iconify의 가져오기·정리 도구를 쓰세요. 글꼴, 외부 이미지, 스타일과 참조 정의는 별도로 확인해야 합니다.

등록 누락과 크기 누락 비교하기

Mermaid 12.0.0으로 별도 브라우저 문서에서 이 다이어그램 사본 세 개를 렌더링했습니다. 첫 번째는 등록을 생략했습니다. 두 번째는 잎 경로 두 개를 등록했지만 크기를 생략했습니다. 세 번째는 같은 경로를 width: 32, height: 24로 등록했습니다.

첫 렌더링에서 Mermaid는 사용자 지정 잎 위치에 물음표를 표시했습니다. 출력에 잎 경로가 없었습니다. 두 번째는 출력의 viewBox="0 0 16 16" SVG 안에 경로가 있었고 잎이 눈에 띄게 잘렸습니다. 세 번째는 viewBox="0 0 32 24"를 사용해 완전한 잎이 표시됐습니다.

이 관찰은 해당 예제와 버전을 설명합니다. 모든 호스트가 사용할 수 없는 아이콘을 같은 방식으로 표시한다는 뜻은 아닙니다. 예제는 수동 작성 SVG 경로를 쓰며 PerfectVector 변환 결과가 아닙니다.

아이콘을 더 추가하기 전에 최소 예제의 작동 사본을 보관하세요. 팩 속성을 한 번에 하나씩 바꾸세요. 그렇지 않으면 이름 수정이 별도 크기 문제를 가릴 수 있습니다.

필요할 때 래스터 그림 가져오기

사용자 지정 픽토그램이 PNG나 JPG로만 남았다면 PerfectVector의 클립아트 SVG 변환 작업 흐름이 편집 가능한 윤곽선 복원에 도움이 됩니다. 사본을 픽토그램으로 자르고 벡터 결과를 미리 본 뒤 실루엣, 내부 틈과 원하지 않는 배경 도형을 확인하세요. 편집기에서 SVG를 열고 다이어그램에 사용할 작은 버전을 준비하세요.

편집 가능한 SVG 원본을 유지하세요. 의도한 아이콘 크기에서 명확하게 읽힌 후에만 그리기 콘텐츠와 좌표를 패키징하세요. 단순한 기하 심볼은 다시 그리는 편이 빠를 수 있고 사진은 별도 이미지로 더 명확할 수 있습니다. 적합한 SVG 그림이 이미 있다면 패키징 단계부터 시작하세요.

벡터화는 다이어그램의 서비스 이름, 관계나 연결선 방향을 복원하지 않습니다. 이는 Mermaid 소스에 두세요. 다른 도형 동작의 캔버스 편집기는 draw.io 사용자 지정 SVG 도형을 참고하세요. 일반 웹페이지의 재사용 아이콘에는 SVG 심볼 스프라이트가 다른 패키징 방식입니다. DOT 다이어그램은 Graphviz SVG 노드 이미지 전달에서 내보낸 그래프와 사용자 지정 그림이 함께 전달되는지 확인하세요.

다이어그램을 전달하기 전에 실제 게시 작업 흐름으로 다시 여세요. 아이콘 로딩, 전체 실루엣 맞춤, 두 레이블의 가독성과 연결선 방향을 확인하세요. 로컬 렌더링 성공은 시작 검사이고 이후 대상 검사가 필요합니다.

FAQ

Mermaid 아이콘 참조 안에 SVG 파일명을 넣어도 되나요? 등록 아이콘 팩 작업에는 garden:leaf 같은 팩 이름과 아이콘 키를 쓰세요. SVG 그림을 아이콘 데이터로 준비하고 렌더러 JavaScript에서 팩을 등록하세요.

사용자 지정 Mermaid 아이콘이 잘리는 이유는 무엇인가요? 원본 viewBox와 아이콘 데이터의 좌표 속성을 비교하세요. 아이콘과 세트 모두 크기가 없으면 너비·높이 기본값은 16이며 그림에 너무 작을 수 있습니다.

모든 호스팅 Markdown 편집기에서 작동하나요? 아닙니다. 호스트가 다이어그램 문법을 지원하고 필요한 팩을 등록할 방법을 제공하거나 이미 포함해야 합니다. 로컬 설정과 같다고 가정하지 말고 실제 게시 대상을 테스트하세요.

Sources

1. Mermaid — 아이콘 팩 등록 — 직접 아이콘 데이터, 로더와 등록 이름을 설명합니다.
2. Mermaid — 아키텍처 다이어그램 — 서비스 아이콘, 네이티브 레이블, 기본 아이콘과 간선 문법을 정의합니다.
3. Iconify — IconifyIcon — SVG 래퍼 없는 그림 콘텐츠와 좌표 속성을 정의합니다.
4. Iconify — IconifyJSON — 팩 구조와 아이콘이 상속하는 크기 기본값을 정의합니다.

다이어그램의 픽토그램이 래스터로만 있나요? PerfectVector로 SVG 후보를 준비하고 실루엣과 틈을 확인하세요. 아이콘 하나를 등록한 뒤 최종 Mermaid 렌더러에서 경계와 레이블을 검증하세요.