Skip to content

feat: mermaid 다이어그램 렌더링 기능 추가#672

Open
vanillacake369 wants to merge 4 commits into
velopert:masterfrom
vanillacake369:fix/mermaid
Open

feat: mermaid 다이어그램 렌더링 기능 추가#672
vanillacake369 wants to merge 4 commits into
velopert:masterfrom
vanillacake369:fix/mermaid

Conversation

@vanillacake369
Copy link
Copy Markdown

@vanillacake369 vanillacake369 commented May 11, 2026

개요

아래와 같은 mermaid 코드 블록을 다이어그램(SVG)으로 렌더링하는 기능을 추가합니다.

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
Loading

변경사항

  • mermaid 코드 블록을 <pre class="mermaid"> placeholder로 변환하는 remark 플러그인 추가
  • prismPlugin에서 mermaid 블록을 스킵하여 코드 하이라이팅 충돌 방지
  • MarkdownRender에서 mermaid 블록 감지 시 CDN으로 mermaid.js를 동적 로드하여 SVG 렌더링
  • 코드 테마(atom-one/monokai/dracula)에 따라 mermaid dark/default 테마 자동 전환

테스트

# 단위 테스트 (8개)
node scripts/test.js --watchAll=false --testPathPattern="src/lib/remark/__tests__"

# 시각 테스트 (백엔드 불필요)
open test-mermaid.html

논의사항

이슈 : mermaid npm 패키지와 현재 빌드 환경의 호환성

mermaid npm 패키지는 optional chaining 등 최신 JS 문법을 사용하고 있어, 현재 프로젝트의 babel/webpack 설정에서 `ERR: optionalChaining isn't currently enabled` 에러가 발생합니다. 이로 인해 npm 패키지를 직접 번들링할 수 없습니다.

대안

이에 대해 다음과 같은 대안들이 있으며, 현재는 CDN 동적 로딩을 선택하여 mermaid.js를 런타임에 불러오고 있습니다. 기존 프로젝트에서 Twitter widgets, KaTeX CSS를 CDN으로 로딩하는 패턴과 일관되고, 빌드 설정 변경 없이 적용 가능하기 때문입니다.

대안 장점 단점
CDN 동적 로딩 (현재) 번들 사이즈 증가 없음, babel 충돌 없음, 기존 패턴과 일관됨 외부 CDN 의존, 오프라인 미지원
npm + babel 플러그인 추가 버전 고정, 오프라인 지원 `@babel/plugin-proposal-optional-chaining` 추가 + webpack 설정 수정 필요, 번들 ~2MB 증가

리뷰어 요청사항 : npm 패키지 방식으로 전환이 필요한지, CDN 버전을 `mermaid@11`(메이저 고정)로 유지할지 `mermaid@11.4.1`(정확 고정)로 변경할지에 대해 의견 부탁드립니다

@vanillacake369
Copy link
Copy Markdown
Author

CI 실패 관련 참고

4개의 Netlify CI(Header rules, Pages changed, Redirect rules, deploy-preview)가 실패하고 있으나, 이는 본 PR의 변경사항과 무관합니다.

Convert mermaid code blocks into renderable placeholder HTML
(<div class="mermaid-block"><pre class="mermaid">) so that
mermaid.js can pick them up on the client side.
Prevent Prism.js from syntax-highlighting mermaid code blocks,
which would turn diagram definitions into colored code text
instead of renderable diagrams.
- Add mermaidPlugin to remark pipeline (SSR + client)
- Dynamically load mermaid.js from CDN when mermaid blocks detected
- Auto-switch mermaid theme based on code theme setting
- Add .mermaid-block styles for centered, responsive diagrams
- mermaidPlugin: 5 unit tests (transform, skip non-mermaid, diagram types)
- prismPlugin: 3 unit tests (mermaid skip, JS highlight, plain code)
- test-mermaid.html: standalone visual test (10 cases, no backend needed)
@vanillacake369 vanillacake369 changed the title feat: add mermaid diagram rendering support feat: mermaid 다이어그램 렌더링 기능 추가 May 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant