Mermaid 인터랙티브 가이드 개발기 🎨

Eunjae Tony Lee·2025년 12월 10일

DEV

목록 보기
1/2

배포 링크: https://mermaid-interactive-guide.vercel.app
GitHub: Repository

🤔 왜 만들었나요?

회사에서 기획서나 문서를 작성할 때마다 다이어그램이 필요했습니다. PowerPoint로 그리자니 시간이 오래 걸리고, 수정할 때마다 일일이 박스를 움직여야 했죠.

그러던 중 Mermaid라는 도구를 알게 되었습니다. 텍스트 몇 줄이면 다이어그램이 완성되는 신기한 도구였어요! 하지만 주변 동료들은 "어려워 보인다", "배우기 힘들 것 같다"는 반응이었습니다.

"5분이면 누구나 배울 수 있다"는 걸 보여주고 싶어서 이 가이드를 만들게 되었습니다.

💡 핵심 아이디어

1. 인터랙티브 학습

단순히 보기만 하는 튜토리얼이 아니라, 직접 코드를 수정하고 결과를 바로 확인할 수 있도록 만들었습니다.

graph LR
    A[코드 수정] --> B[버튼 클릭] --> C[결과 확인]

각 레슨마다 "✏️ 직접 수정해보기" 버튼을 누르면 코드 에디터가 나타나고, 사용자가 직접 수정해볼 수 있습니다.

2. 단계별 학습

초보자도 따라올 수 있도록 13개의 단계로 나누었습니다:

  • Lesson 0-9: 기본 문법 (박스, 화살표, 방향, 분기 등)
  • Lesson 10: Claude AI와 연동하는 법
  • Lesson 11: 이미지로 저장하는 법
  • Lesson 12: 실무 활용 사례
  • Lesson 13: 완료!

3. Claude AI 연동 강조

가장 중요한 포인트는 "직접 그리지 마세요!"입니다.

Mermaid 문법을 외울 필요 없이, Claude한테 "○○○ 다이어그램 그려줘"라고 하면 몇 초만에 완성됩니다. 이 가이드의 목적은:

  • Mermaid가 무엇인지 이해하기
  • Claude가 만든 다이어그램을 읽고 수정할 수 있게 되기
  • 실무에서 어떻게 활용할지 감 잡기

🛠️ 기술 스택

심플하게!

  • Mermaid.js v10 - 다이어그램 렌더링
  • Vanilla JavaScript - 인터랙티브 기능
  • CSS3 - 반응형 디자인 & 애니메이션
  • Vercel - 배포

프레임워크 없이 순수 HTML/CSS/JS로 만들었습니다. 가볍고 빠르게 동작하는 것이 목표였어요!

🎨 디자인 & UX

그라디언트와 애니메이션

보라색 그라디언트(#667eea → #764ba2)를 메인 컬러로 사용했습니다. 시각적으로 눈에 띄면서도 부담스럽지 않은 색상이에요.

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

"✏️ 직접 수정해보기" 버튼에는 펄스 애니메이션을 적용해서 "클릭해보세요!"라는 느낌을 주었습니다:

@keyframes pulse-button {
    0%, 100% {
        box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
    }
    50% {
        box-shadow: 0 4px 25px rgba(102, 126, 234, 0.6);
        transform: scale(1.02);
    }
}

목차 네비게이션

오른쪽에 고정된 목차(TOC)를 만들어서 언제든지 원하는 레슨으로 점프할 수 있게 했습니다. 모바일에서는 자동으로 숨겨지고, 📑 버튼을 눌러서 열 수 있어요.

🚧 개발 과정에서 겪은 문제들

1. 다이어그램 렌더링 이슈

사용자가 코드를 수정하고 "🎨 그리기" 버튼을 누를 때, Mermaid가 제대로 렌더링되지 않는 문제가 있었습니다.

해결 방법: 기존 DOM을 완전히 제거하고 새로 만든 다음, mermaid.init()을 다시 호출했습니다.

function renderCode(lessonNum) {
    const code = document.getElementById('code-' + lessonNum).value;
    const preview = document.getElementById('preview-' + lessonNum);

    // 기존 내용 제거
    preview.innerHTML = '';

    // 임시 div 생성
    const tempDiv = document.createElement('div');
    tempDiv.innerHTML = '<div class="mermaid">' + code + '</div>';

    // preview에 추가
    preview.appendChild(tempDiv);

    // Mermaid 다시 초기화
    mermaid.init(undefined, tempDiv.querySelector('.mermaid'));
}

2. 다이어그램 크기 조절

사용자가 큰 다이어그램을 만들면 화면을 넘어가는 문제가 있었습니다.

해결 방법:

  • SVG의 max-width를 500px로 제한
  • 스크롤이 가능하도록 overflow: auto 적용
  • 모바일에서는 100% width로 자동 조절
.editor-container .preview-box svg {
    max-width: 500px !important;
    max-height: 500px !important;
    width: auto !important;
    height: auto !important;
}

3. SEO & 소셜 미디어 최적화

카카오톡이나 슬랙에 링크를 공유했을 때 예쁜 미리보기가 나오도록 Open Graph 메타 태그를 추가했습니다.

<meta property="og:title" content="Mermaid 다이어그램 - 인터랙티브 가이드">
<meta property="og:description" content="텍스트로 다이어그램을 그리는 Mermaid를 5분만에 배워보세요!">
<meta property="og:image" content="https://mermaid-interactive-guide.vercel.app/OG_image.png">

OG 이미지는 1792x1024 크기의 PNG 파일로 만들었어요!

📈 반복적인 개선

Git 커밋 히스토리를 보면 반복적으로 개선한 흔적이 보입니다:

  1. 첫 번째 버전: 기본 가이드 완성 (bf715f9)
  2. 시스템 아키텍처 추가 (dc4e49c)
  3. Vercel 배포 URL 추가 (79e7c81)
  4. "직접 해보세요" 버튼 강조 (c52623b) - 사용자가 인터랙티브 요소를 놓치지 않도록!
  5. 제작자 크레딧 추가 (e840a79)
  6. 다이어그램 오버플로우 수정 (ca1c152, 77063d8, ...)
  7. SVG 크기 조절 (ea1319f, b841265, ...)
  8. 재시작 버튼 추가 (3131110)
  9. Favicon & 소셜 미디어 태그 (6e393f8)
  10. OG 이미지 업데이트 (0ce030c)

특히 다이어그램 크기 문제는 여러 번 커밋을 거쳐 해결했습니다. 사용자 경험을 위해 계속 테스트하고 개선했어요!

🎯 타겟 사용자

이 가이드는 다음 분들을 위해 만들었습니다:

  • 📝 기획자: 기획서에 플로우차트를 추가하고 싶은데 어떻게 해야 할지 모르는 분
  • 💻 개발자: API 플로우나 시스템 구조를 설명해야 하는데 PPT 그리기 귀찮은 분
  • 📊 PM: 프로젝트 프로세스를 시각화하고 싶은 분
  • 🎓 다이어그램 툴 입문자: 처음 배우는 모든 분

💪 실무 활용 예시

가이드에서 소개한 실무 활용 사례입니다:

1. 기획자: 좋아요 버튼 클릭 플로우

graph LR
    Click[좋아요 버튼 클릭] --> Check{로그인<br/>했나요?}
    Check -->|아니오| Login[로그인 화면]
    Check -->|예| Like[하트 빨강게 변함]
    Like --> Count[숫자 1 증가]

2. 개발자: 코드 수정 & 배포 프로세스

graph LR
    Code[코드 수정] --> Test[내 컴퓨터에서 테스트]
    Test --> Push[GitHub에 올리기]
    Push --> Review[팀장님 확인]
    Review --> Deploy[서버에 배포]

3. PM: 고객 문의 처리

graph TD
    Start([문의 접수]) --> Type{문의 유형?}
    Type -->|배송 문의| Ship[배송팀에 전달]
    Type -->|환불 요청| Refund[환불 처리]
    Type -->|상품 문의| Answer[답변 작성]

    Ship --> Done([완료])
    Refund --> Done
    Answer --> Done

🚀 배포

Vercel로 배포했습니다. 설정이 거의 필요 없고, Git push만 하면 자동으로 배포되어서 정말 편리했어요!

배포 과정:
1. GitHub에 레포 push
2. Vercel에서 "New Project" 클릭
3. GitHub 레포 선택
4. Deploy 버튼 클릭
5. 완료! 🎉

커스텀 도메인도 쉽게 연결할 수 있지만, 일단 Vercel 도메인(mermaid-interactive-guide.vercel.app)을 사용하고 있습니다.

📊 성과 & 피드백

목표 달성

  • ✅ 5분만에 Mermaid 기본 문법 이해
  • ✅ Claude AI와 연동하는 법 학습
  • ✅ 실무 활용 방법 습득
  • ✅ 인터랙티브하게 직접 수정하며 배우기

앞으로의 계획

  • 더 많은 다이어그램 타입 추가 (시퀀스 다이어그램, 클래스 다이어그램 등)
  • 실전 예제 더 추가
  • 다국어 지원 (영문 버전)
  • 사용자 피드백 수집 & 개선

🎓 배운 점

1. 단순함의 힘

프레임워크 없이 Vanilla JS로 만들었지만, 충분히 인터랙티브하고 반응성 있는 웹사이트를 만들 수 있었습니다. 때로는 단순한 것이 더 강력합니다!

2. 사용자 경험이 최우선

다이어그램 크기, 버튼 애니메이션, 목차 네비게이션 등 작은 디테일이 사용자 경험을 크게 바꿉니다. 커밋 히스토리를 보면 사용자 경험 개선에 많은 시간을 투자했다는 걸 알 수 있어요.

3. 반복적인 개선의 중요성

첫 번째 버전은 완벽하지 않았습니다. 하지만 계속 테스트하고 개선하면서 점점 나아졌어요. "완벽해질 때까지 기다리지 말고, 일단 만들고 개선하자!"

4. 메타 태그의 중요성

OG 이미지와 메타 태그를 추가하니 링크를 공유했을 때 훨씬 전문적으로 보였습니다. SEO와 소셜 미디어 최적화는 정말 중요해요!

🙏 마치며

처음에는 "동료들에게 Mermaid를 알려주고 싶다"는 단순한 목표로 시작했지만, 만들면서 많은 걸 배웠습니다.

특히 "사용자가 직접 수정하며 배우는 것"의 중요성을 깨달았어요. 단순히 보는 것과 직접 해보는 것은 완전히 다릅니다!

이 가이드가 더 많은 분들에게 Mermaid의 편리함을 알리는 계기가 되었으면 좋겠습니다 🎉

배포 링크: https://mermaid-interactive-guide.vercel.app

질문이나 피드백은 언제든지 환영합니다! 슬랙 @루쿠쿠 이은재 Tony로 연락주세요 🙌

Happy Diagramming! 🎨✨

profile
Eunjae Tony Lee
철학하는 개발자출신 Project Manager
다음 포스트

로그인 북마크렛 생성기 개발기 🔐

0개의 댓글