티스토리 스킨에 Mermaid 다이어그램 적용하기

티스토리 스킨에 Mermaid 다이어그램 적용하기

GitHub README나 Notion에서 자주 보는 편리한 Mermaid 다이어그램, 티스토리 블로그에서도 쓰고싶다면 아래 글 참고해서 적용하시면 좋을거 같습니다.

티스토리 기본 마크다운 에디터에 ```mermaid 블록을 넣으면 도식이 아닌 단순한 회색 코드블록으로만 표시됩니다. 이 글에서는 티스토리 인기 스킨인 hELLO 스킨을 간단히 수정해 실제 도식으로 렌더링되도록 만드는 방법을 정리해 보았습니다.

💡 적용 후 모습 미리보기
설정 완료 후 아래 예제 섹션의 플로우차트나 시퀀스 다이어그램 코드를 복사해서 새 글에 붙여넣었을 때, 텍스트가 아닌 정상적인 그림(도식)으로 그려진다면 성공입니다.

🧐 왜 수정이 필요한가요?

hELLO 스킨은 코드블록의 문법 색상을 입히기 위해 highlight.js를 사용합니다. 하지만 스킨 자체에 Mermaid 라이브러리는 포함되어 있지 않기 때문에, ```mermaid 블록을 작성하면 아래처럼 단순 텍스트로 취급되어 렌더링됩니다.

<pre class="hljs"><code class="language-mermaid">graph TD
  A --> B</code></pre>

Mermaid 라이브러리는 기본적으로 <div class="mermaid"> 태그 안에 있는 텍스트만 읽어서 SVG 도식으로 변환합니다. 따라서 다음 두 가지 작업이 필요합니다.

1. Mermaid 라이브러리를 스킨에 불러오기
2. code.language-mermaid 태그를 <div class="mermaid">로 변환한 뒤 렌더링 실행하기

🚀 적용 방법

1단계: 스킨 편집 열기

티스토리 관리자 페이지에 접속한 뒤, 꾸미기 → 스킨 편집 → 우측 상단의 html 편집 탭으로 이동합니다.

2단계: </head> 직전에 스크립트 추가

index.html 파일 안에서 </head> 닫는 태그를 찾습니다. (보통 맨 위에서 조금 아래쪽에 있습니다.) 그 바로 위에 아래의 코드를 복사해서 붙여넣으세요.

<!-- CUSTOM: Mermaid 다이어그램 지원 -->
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';

  const renderMermaid = () => {
    document.querySelectorAll('pre code.language-mermaid').forEach((code) => {
      const pre = code.closest('pre');
      const div = document.createElement('div');
      div.className = 'mermaid';
      // hljs가 감싼 <span> 태그들이 있어도 textContent로 순수 원본 코드만 복원
      div.textContent = code.textContent;
      pre.replaceWith(div);
    });

    const isDark = document.documentElement.classList.contains('dark');
    mermaid.initialize({
      startOnLoad: false,
      theme: isDark ? 'dark' : 'default',
      securityLevel: 'loose',
    });
    mermaid.run({ querySelector: '.mermaid:not([data-processed="true"])' });
  };

  window.addEventListener('load', renderMermaid);
</script>

3단계: 저장 및 확인

스킨 편집 상단의 [적용] 버튼을 누르면 끝입니다! 기존 글이나 새 글을 열어보면 Mermaid 마크다운 블록이 멋진 도식으로 변환되어 있을 것입니다.

⚙️ 코드가 하는 일 (핵심 요약)

코드 요소	역할
type="module"	ES module import 사용을 가능하게 합니다.
cdn.jsdelivr.net	Mermaid v10 라이브러리를 CDN에서 가져옵니다.
load 이벤트	hELLO 스킨의 app.js(hljs 작동)가 먼저 실행된 이후에 도식을 변환하도록 순서를 보장합니다.
code.language-mermaid	마크다운의 ```mermaid 블록이 HTML로 변환될 때 생성되는 클래스입니다.
textContent	hljs가 색상을 입히느라 추가한 <span> 태그를 무시하고 순수 텍스트(코드)만 추출합니다.
pre.replaceWith(div)	기존 코드블록의 배경이나 패딩 CSS가 도식에 영향을 주지 않도록 통째로 교체합니다.
theme: isDark ...	스킨의 다크/라이트 테마 상태를 감지하여 도식의 색상 테마를 맞춥니다.
startOnLoad: false	페이지 로드 시 자동 스캔하는 대신, 우리가 태그를 수정한 직후 수동으로 실행(mermaid.run)하여 타이밍 오류를 방지합니다.

🎨 테스트용 예제 모음

적용이 완료되었다면 아래 코드들을 블로그 새 글(마크다운 모드)에 그대로 붙여넣어 보세요. 모두 정상적인 도식으로 그려져야 합니다.

예제 1. 플로우차트 (Flowchart)

가장 자주 쓰이는 형태입니다. 분기나 흐름을 표현할 때 유용합니다.

graph TD
  A[사용자 요청] --> B{인증됨?}
  B -- Yes --> C[데이터 조회]
  B -- No --> D[로그인 페이지]
  C --> E[응답 반환]
  D --> E

예제 2. 시퀀스 다이어그램 (Sequence Diagram)

시스템 간 통신이나 API 호출 순서를 설명하는 데 적합합니다.

sequenceDiagram
  participant U as 사용자
  participant W as 웹서버
  participant D as DB
  U->>W: GET /posts
  W->>D: SELECT * FROM posts
  D-->>W: 결과 반환
  W-->>U: JSON 응답

예제 3. 상태 다이어그램 (State Diagram)

주문 상태, 워크플로우 등 상태의 변화를 설명할 때 좋습니다.

stateDiagram-v2
  [*] --> 대기중
  대기중 --> 처리중 : 접수
  처리중 --> 완료 : 성공
  처리중 --> 실패 : 오류
  완료 --> [*]
  실패 --> 대기중 : 재시도

예제 4. 클래스 다이어그램 (Class Diagram)

객체 지향 프로그래밍의 클래스 관계를 설명할 때 사용합니다.

classDiagram
  class Animal {
    +String name
    +int age
    +eat()
  }
  class Dog {
    +String breed
    +bark()
  }
  class Cat {
    +boolean indoor
    +meow()
  }
  Animal <|-- Dog
  Animal <|-- Cat

예제 5. 간트 차트 (Gantt Chart)

프로젝트 일정이나 로드맵을 공유할 때 유용합니다.

gantt
  title 프로젝트 일정
  dateFormat YYYY-MM-DD
  section 설계
  요구사항 분석  :a1, 2026-04-01, 7d
  아키텍처 설계  :a2, after a1, 5d
  section 개발
  백엔드 구현   :b1, after a2, 14d
  프론트엔드 구현 :b2, after a2, 14d
  section 테스트
  통합 테스트   :c1, after b1, 5d

예제 6. 파이 차트 (Pie Chart)

비율을 간단하게 시각화할 때 좋습니다.

pie title 블로그 방문자 유입 경로
  "검색엔진" : 55
  "SNS" : 25
  "직접방문" : 15
  "기타" : 5

예제 7. ER 다이어그램 (ER Diagram)

데이터베이스 설계 글을 쓸 때 필수적입니다.

erDiagram
  USER ||--o{ POST : writes
  USER {
    int id PK
    string email
    string name
  }
  POST ||--o{ COMMENT : has
  POST {
    int id PK
    int user_id FK
    string title
    text body
  }
  COMMENT {
    int id PK
    int post_id FK
    text content
  }

⚠️ 한계 및 참고사항

1. 다크모드 실시간 전환 미반영
   페이지가 로드되는 시점의 테마를 기준으로 딱 한 번 렌더링됩니다. 우측 하단의 테마 토글 버튼을 눌러도 이미 그려진 다이어그램의 색상은 즉시 바뀌지 않습니다. (새로고침을 하면 바뀐 테마로 다시 그려집니다.)
   ※ 완벽한 반응형으로 만들려면 MutationObserver로 HTML 클래스 변화를 감지해야 하지만, 복잡도가 커지므로 실용성을 위해 현재 상태를 권장합니다.

2. CDN 네트워크 의존성
   jsDelivr CDN에서 라이브러리를 불러오기 때문에, 네트워크 환경에 따라 페이지 로드 후 아주 잠깐 코드블록 텍스트가 보이다가 도식으로 바뀔 수 있습니다. 최적화가 필요하다면 Mermaid 번들 파일을 티스토리에 직접 업로드 후 로컬 경로로 호출하면 됩니다.

3. 버전 호환성
   본문의 코드는 Mermaid v10 기준입니다. 최신 v11로 올리려면 import URL의 mermaid@10을 mermaid@11로 변경하면 됩니다. 단, 메이저 버전업 시 일부 문법이나 설정이 변경될 수 있으므로 기존 도식이 잘 나오는지 반드시 확인하세요.