[Nextra] Mermaid Gantt 차트 반응형 적용

📊 Mermaid Gantt 차트 반응형 적용기 (with clientMermaid)

---

📌 Mermaid 공식 플러그인 사용 배경

1. Gantt 차트 사용

1. botbox 프로젝트 문서에 타임라인 시각화를 위해 Mermaid의 Gantt 차트를 도입함
2. Nextra에서 기본적으로 지원하는 ```mermaid 코드 블록 형식에는 Gantt가 포함되어 있지 않음
3. Mermaid 공식 플러그인을 직접 설치하여 Gantt를 사용

 

2. 하나의 .mdx파일에서 2개의 Mermaid 컴포넌트 사용

2025.04.09 - [문서 정리 프레임워크/Nextra] - [Nextra] Mermaid 플러그인에서 발생하는 렌더링 충돌 오류 해결

[Nextra] Mermaid 플러그인에서 발생하는 렌더링 충돌 오류 해결

---

🧩 문제점

1. botbox 문서에 Gantt 타임라인 차트를 도입했는데, 레이아웃이 작아지면 오히려 막대와 텍스트가 커지고, 레이아웃이 커지면 작아지는 비정상적인 반응을 보임

2. 화면이 작아지면 너무 큰 막대와 글씨가 생겨 스크롤이 생기고, 큰 화면에서는 글씨가 너무 작아서 읽을 수 없는 상태

3. 읽을 수 있게 끔 화면이 클때 막대와 글씨가 같이 커져 작을 때 맞춰서 작아지게 반응형으로 제작하려함

4. 아래 Mermaid v10+에서 도입된 Inline Configuration 방식은 themeVariables보다 우선 적용 및 렌더링 시점에 적용되지만 반응형이라고 보기에는 한계가 있음(window 크기별 동적 조정 불가, 한 번 렌더된 후 값 고정)

%%{init: {
  "gantt": {
    "axisFormat": "%m/%d", // 날짜 포맷
    "barHeight": 48,       // 막대 높이
    "fontSize": 24         // 폰트 크기
}}%%

---

🧨 원인 분석

1. mermaid.initialize({...}) 안의 fontSize, barHeight, tickInterval이 초기 렌더 시 고정값으로만 지정되었음

2. 화면 크기가 변해도 Mermaid 자체는 다시 그려지지 않기 때문에 레이아웃 변경이 적용되지 않음

3. 반응형 스타일 속성 (width: 100%, preserveAspectRatio, max-width)만으로는 차트 내부 요소(barHeight, fontSize)까지 조정할 수 없음

---

🛠️ 해결 과정

1. window.innerWidth 기준으로 fontSize, barHeight, tickInterval을 설정하는 반응형 렌더링 함수를 제작

2. mermaid.mermaidAPI.reset()로 이전 렌더 캐시 제거 후 mermaid.initialize() 재설정

3. renderChart()를 window.addEventListener('resize', ...)에 바인딩하여 리사이즈 감지 후 자동 재렌더

4. 서버사이드 렌더링 환경에서는 window is not defined 오류 발생 → .mdx 내부에서 dynamic(() => import('clientMermaid'), { ssr: false })로 해결

---

✅ 최종 적용 코드

const screenWidth = window.innerWidth;
const fontSize = screenWidth >= 1800 ? 34 : screenWidth >= 1400 ? 28 : screenWidth >= 1024 ? 22 : 14;
const barHeight = screenWidth >= 1800 ? 60 : screenWidth >= 1400 ? 52 : screenWidth >= 1024 ? 44 : 36;
const tickInterval = screenWidth >= 1400 ? "2week" : "4week";

mermaid.initialize({
  startOnLoad: false,
  theme,
  gantt: {
    fontSize,
    barHeight,
    tickInterval,
    ...
  },
});

---

📈 구현 효과 및 결과

1. 이제 화면 크기에 따라 막대(bar)와 글씨(font)의 크기가 유동적으로 조절됨

2. 작은 화면에서는 막대와 글씨가 작아지고, 큰 화면에서는 시원하게 커져 가독성 향상

3. tick 간격도 화면 크기에 따라 2week ↔ 4week로 유연하게 변경되어, 정보 밀도가 자동으로 조절됨

4. SVG 내부의 노드에도 font-size를 직접 적용하여 실제 렌더된 폰트 크기 오차 없이 일관 유지

5. SSR 환경 문제도 ssr: false를 적용한 clientMermaid로 완전 회피

---

🧾 요약

1. 이전에는 화면이 작아질수록 차트가 더 커지고 화면이 클수록 글씨가 더 작아지는 문제가 발생하였음
2. 지금은 window 크기에 따라 차트 막대와 글자가 함께 커지고 작아지는 이상적인 반응형 Mermaid Gantt 차트로 개선 완료됨