Mermaid 간트 차트 편집기
간트 차트는 일을 달력 위에 올려놓습니다. 무엇이 언제 진행되고, 무엇이 겹치며, 무엇이 끝나야 다음이 시작되는지. 날짜와 의존관계 자체가 논점일 때 씁니다. 순서만 보이면 되고 날짜가 필요 없다면, 순서도가 더 가볍고 일정이 밀려도 썩지 않습니다.
의존관계와 출시 판정이 있는 릴리스 계획
이 차트를 그림이 아니라 일정표로 만드는 것은 `after a1`입니다. 의존관계가 선언되어 있어서 앞의 작업을 옮기면 뒤가 모두 따라옵니다. 마일스톤은 기간을 갖지 않는 한 점으로, 출시 판정 회의처럼 날짜만 정해진 일에 씁니다.
gantt
title 주문관리 시스템 2.4 릴리스
dateFormat YYYY-MM-DD
axisFormat %m/%d
excludes weekends
section 개발
요구사항 정의 :done, a1, 2026-01-06, 10d
설계 :active, a2, after a1, 15d
구현 : a3, after a2, 20d
section 시험
단위 테스트 : b1, after a3, 8d
통합 테스트 :crit, b2, after b1, 10d
section 릴리스
출시 판정 회의 :milestone, m1, after b2, 0d
운영 배포 :crit, b3, after m1, 2d예제로 익히기
1. 가장 단순한 차트
`dateFormat`은 적은 날짜를 「어떻게 읽을지」이고, `axisFormat`은 축에 「어떻게 표시할지」입니다. 서로 다른 설정이며, 이 둘을 헷갈리는 것이 간트에서 가장 흔한 막힘입니다.
gantt
title 스프린트 14
dateFormat YYYY-MM-DD
section 작업
검색 기능 구현 :2026-03-02, 10d2. 작업 ID와 의존관계
작업에 ID를 주면 뒤의 작업이 `after <ID>`라고 쓸 수 있습니다. ID는 영숫자로 두는 편이 무난합니다. 의존관계를 선언해 두면 시작일을 한 곳만 고쳐도 나머지가 따라옵니다.
gantt
title 고객 데이터 이관
dateFormat YYYY-MM-DD
section 준비
현행 스키마 조사 :a1, 2026-02-02, 5d
변환 매핑 작성 :a2, after a1, 8d
section 실행
리허설 :a3, after a2, 3d
전환 :a4, after a3, 1d3. 상태 키워드
`done`, `active`, `crit`은 막대가 그려지는 방식을 바꿉니다. 「계획은 이렇습니다」로 끝나는 차트를 「지금 어디까지 왔습니다」에 답하는 차트로 바꾸는 가장 값싼 방법입니다.
gantt
title 1분기 플랫폼 정비
dateFormat YYYY-MM-DD
section 인프라
Terraform 정리 :done, t1, 2026-01-05, 12d
Kubernetes 업그레이드 :active, t2, 2026-01-19, 15d
비용 점검 : t3, after t2, 5d
section 보안
의존성 점검 :crit, s1, 2026-01-12, 6d4. 마일스톤
마일스톤은 기간이 아니라 점이므로 `0d`를 줍니다. 전시회, 계약상 납기, 코드 프리즈처럼 프로젝트 바깥에서 날짜가 정해진 일에 씁니다.
gantt
title 신규 서비스 공개
dateFormat YYYY-MM-DD
section 개발
기능 동결 :milestone, m1, 2026-04-01, 0d
버그 수정 기간 : e1, 2026-04-01, 5d
릴리스 브랜치 :milestone, m2, after e1, 0d
section 홍보
보도자료 해제 :milestone, m3, 2026-04-15, 0d5. 주말과 공휴일 제외
`excludes weekends`를 쓰면 기간 계산에서 토요일과 일요일이 빠집니다. 10일짜리 작업이 주말을 넘어 두 주에 걸치게 되고, 이것이 「현장이 믿는 차트」와 「조용히 무시되는 차트」를 가르는 경우가 많습니다. 공휴일은 날짜별로 하나씩 지정합니다. 설과 추석이 낀 분기에서는 이 차이가 큽니다.
gantt
title 신규 서비스 인수인계
dateFormat YYYY-MM-DD
excludes weekends, 2026-03-01, 2026-05-05
section 구축
환경 구축 :p1, 2026-05-07, 5d
CI/CD 정비 :p2, after p1, 5d
section 인계
운영 문서와 교육 :p3, after p2, 4d간트 문법 요약
여기서 다루는 여섯 종류 가운데 간트는 작업 행이라는 한 곳만 엄격하고 나머지는 한없이 너그럽습니다. 간트의 실수가 조용히 지나가는 이유가 바로 그것입니다.
| 문법 | 뜻 |
|---|---|
| gantt | 다이어그램을 시작합니다. |
| title 글자 | 차트 제목. |
| dateFormat YYYY-MM-DD | 적은 날짜를 읽어 들이는 형식. |
| axisFormat %m/%d | 축에 표시하는 형식. dateFormat과는 다른 설정. |
| excludes weekends | 기간 계산에서 토·일요일을 뺍니다. |
| excludes 2026-05-05 | 특정 날짜를 제외합니다. 공휴일은 이렇게 지정합니다. |
| section 이름 | 작업을 띠로 묶습니다. |
| 작업명 :id, 2026-01-01, 10d | 시작일과 기간을 명시한 작업. |
| 작업명 :id, after 다른id, 10d | 다른 작업이 끝난 뒤 시작하는 작업. |
| 작업명 :done, id, ... | 완료 — 흐리게 그려집니다. |
| 작업명 :active, id, ... | 진행 중 — 강조해서 그려집니다. |
| 작업명 :crit, id, ... | 중요 — 강조색으로 그려집니다. |
| 이름 :milestone, id, 날짜, 0d | 기간이 아니라 시점. |
| 10d / 3w / 2h | 일·주·시간. 단위는 생략할 수 없습니다. |
간트의 함정 여섯 가지 — 오류가 나는 건 하나뿐
이것이 간트와 나머지 다섯 종류의 결정적인 차이입니다. Mermaid 11.12.2에서 재현한 결과, 아래 여섯 중 그리기가 멈추는 것은 하나뿐이었습니다. 나머지 다섯은 그럴듯한 차트를 그려 놓고 틀립니다. 그려진 그림을 다시 의심하는 사람은 없으므로 그쪽이 훨씬 위험합니다.
보이는 증상
Parse error, 끝부분: Expecting 'taskData', got 'NL'
원인
작업 행에 콜론이 없습니다. 콜론은 표시 이름과 데이터를 나누는 기호이고, 이것이 없으면 읽을 데이터가 존재하지 않습니다. 이 목록에서 Mermaid가 명확히 거부하는 것은 이것뿐입니다.
해결
작업명과 ID 사이에 콜론을 넣습니다.
gantt
dateFormat YYYY-MM-DD
section 작업
설계 a1, 2026-01-06, 5dgantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026-01-06, 5d보이는 증상
그려지기는 하는데 작업명이 도중에 잘려 있다
원인
작업명 안에 콜론이 있습니다. 첫 콜론이 구분자이므로 그 뒤는 작업 데이터로 읽힙니다. `1단계: 설계`는 `1단계`라는 작업이 되고 「설계」는 사라집니다.
해결
작업명에 콜론을 넣지 마세요. 붙임표나 쉼표로 바꾸거나, 세부는 섹션 이름으로 옮깁니다.
gantt
dateFormat YYYY-MM-DD
section 작업
1단계: 설계 :a1, 2026-01-06, 10dgantt
dateFormat YYYY-MM-DD
section 작업
1단계 - 설계 :a1, 2026-01-06, 10d보이는 증상
그려지기는 하는데 축이 갑자기 몇 달로 늘어난다
원인
`after`가 존재하지 않는 작업 ID를 가리키고 있습니다. ID 오타이거나 이름을 바꾼 뒤 고치지 않은 경우입니다. Mermaid는 경고 없이 그 작업을 임의의 위치에 두고, 축이 거기까지 닿도록 늘어납니다. 10일짜리 작업 두 개뿐인 그림이 여덟 달치 축이 되기도 합니다.
해결
`after <ID>`가 선언된 ID와 정확히 일치하는지 확인하세요. 축 눈금이 갑자기 성겨지면 이것부터 의심하면 됩니다.
gantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026-03-01, 10d
구현 :a2, after seolgye, 10dgantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026-03-01, 10d
구현 :a2, after a1, 10d보이는 증상
막대가 사라져 점이 된다
원인
기간에 단위가 없습니다. `5`는 5일이 아니라 길이로 해석되지 않습니다. 그래도 차트는 그려지고, 시간을 전혀 쓰지 않는 작업이 있는 것처럼 보입니다.
해결
단위를 반드시 씁니다. `5d`, `3w`, `2h`.
gantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026-03-01, 5gantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026-03-01, 5d보이는 증상
기간은 맞는데 실제 완료일과 어긋난다
원인
`excludes weekends`를 쓰지 않았습니다. 기본값에서 10일은 주말을 포함한 달력 10일이므로, 한 주를 넘는 작업은 차트에서 실제보다 일찍 끝납니다. 한국은 여기에 설과 추석 연휴가 더해져서, 분기를 넘는 계획에서는 차이가 무시할 수 없는 크기가 됩니다.
해결
앞부분에 `excludes weekends`를 넣고, 공휴일은 `excludes 2026-05-05`처럼 따로 제외합니다.
gantt
dateFormat YYYY-MM-DD
section 작업
데이터 이관 :a1, 2026-06-01, 10dgantt
dateFormat YYYY-MM-DD
excludes weekends
section 작업
데이터 이관 :a1, 2026-06-01, 10d보이는 증상
Invalid date:2026년 3월 1일 이라고 나오며 그려지지 않는다
원인
한글로 날짜를 적었는데 `dateFormat`이 `YYYY-MM-DD` 그대로입니다. Mermaid는 선언된 형식으로만 날짜를 해석하므로 년·월·일 글자를 읽지 못하고 멈춥니다. 한국어로 일정표를 쓰기 시작할 때 가장 먼저 부딪히는 지점입니다. 참고로 섹션 이름에는 콜론을 넣어도 잘리지 않습니다. 실측으로 확인했고, 잘리는 것은 작업명뿐입니다.
해결
적는 방식에 맞춰 `dateFormat YYYY년 M월 D일`이라고 선언합니다. 선언만 하면 한글 표기가 그대로 통합니다.
gantt
dateFormat YYYY-MM-DD
section 작업
설계 :a1, 2026년 3월 1일, 10dgantt
dateFormat YYYY년 M월 D일
axisFormat %m/%d
section 작업
설계 :a1, 2026년 3월 1일, 10d렌더링에 관한 메모
모두 이 사이트가 쓰는 Mermaid 11.12.2에서 실측했습니다. 간트는 다른 어떤 종류와도 다르게 동작합니다.
폭이 고정된 유일한 종류입니다
다른 그림은 모두 내용이 늘어난 방향으로 늘어납니다. 간트 차트만은 viewBox의 폭이 언제나 1264픽셀로 고정되어 있고, 작업이 3개든 40개든 달라지지 않습니다. 달라지는 것은 높이뿐으로, 실측에서는 172픽셀에서 1060픽셀까지였습니다. 축은 그 고정 폭에 맞도록 압축되거나 늘어납니다. 2년치 계획과 2주치 계획이 같은 밀도로 보이는 이유입니다. 막대가 너무 가늘어 읽을 수 없다면 원인은 작업 수가 아니라 기간의 폭입니다.
점으로 구분한 날짜는 그대로 통합니다
한국에서 흔히 쓰는 `2026.03.01` 표기는 `dateFormat`이 기본값 `YYYY-MM-DD`인 채로도 3월 1일로 올바르게 읽혔습니다. 실측으로 확인했습니다. 날짜 해석은 선언한 형식보다 너그러운 편이라, 스페인어나 프랑스어에서 `01/03/2026`이 조용히 1월 3일이 되어 버리는 함정을 한국어 표기에서는 대체로 피해 갑니다. 예외는 한글 표기입니다. `2026년 3월 1일`은 너그럽게 넘어가지 않고 Invalid date로 그리기 자체가 멈추므로, 쓰려면 `dateFormat YYYY년 M월 D일`을 함께 선언해야 합니다. 조용히 틀리는 것보다는 눈에 보이게 멈추는 편이니, 간트에서는 드물게 다행인 경우입니다.
PNG 내보내기가 화면과 완전히 일치합니다
간트는 레이블을 HTML이 아니라 순수 SVG 텍스트로 그리기 때문에, 순서도·클래스 다이어그램·상태 다이어그램·ER 다이어그램과 달리 그대로 래스터화할 수 있습니다. 내보낸 PNG는 화면과 한 글자도 다르지 않습니다. 재렌더링이 끼지 않으니 글자 배치가 어긋날 일도 없습니다.
예전에는 PNG 내보내기 피해가 가장 컸습니다
Mermaid는 `width="100%"`를 출력하고 높이 속성을 갖지 않습니다. 예전 이 사이트의 내보내기는 그 크기를 기본값 300×150 상자에 대해 계산했고, 가로로 길고 세로로 짧은 간트의 비율에서는 그것이 최악으로 나타났습니다. 1280×148 차트가 600×58 PNG가 되고 있었습니다. 지금은 viewBox를 읽으므로 같은 차트가 2560×296으로 나옵니다. 예전에 내보낸 간트 PNG가 남아 있다면, 키워도 쓸 수 없습니다.
콜론 말고는 거의 무엇이든 통과합니다
section을 빠뜨려도, 모르는 상태 키워드를 써도, 단위 없는 기간을 적어도 모두 그려집니다. 거부되는 것은 콜론 없는 작업 행뿐입니다. 이 비대칭이 간트를 쓸 때 가장 쓸모 있는 지식입니다. 그려지는 데 성공했다는 사실은 그 차트가 옳다는 것을 거의 아무것도 보장하지 않습니다.
다른 다이어그램이 나은 경우
날짜가 아직 추정에 지나지 않는다면, 간트 차트는 그 추정을 그것이 얻지 못한 정밀도로 제시합니다. 그리고 누군가는 그 날짜로 약속을 잡습니다. 날짜를 갖지 않고 순서만 보여주는 순서도가 더 정직하고, 일정이 움직여도 고칠 필요가 없습니다.
계획이 매주 바뀐다면 텍스트로 적어 버전 관리에 두는 간트는 정말 좋습니다. 무엇이 움직였는지 차이로 보이기 때문입니다. 다만 아무도 갱신하지 않는 차트는 차트가 없는 것보다 나쁩니다. 자신이 만들려는 것이 어느 쪽인지 정직하게 가늠해 보세요.
그리고 인력 평준화나 공수 배분이 논점이라면 도구 선택이 잘못됐습니다. Mermaid는 달력 위에 막대를 그릴 뿐, 누가 그 일을 하는지도 그 사람이 이미 차 있는지도 모릅니다.
다른 다이어그램 종류
작성 Dominik Malsch · 마지막 업데이트: