그림 문법과 배치를 직접 맡고 D2 호환을 버린다
배경
첫 구현은 D2 원본을 받아 D2.js로 배치하고, 그 좌표 위에 다른 모양과 크기의 도형을 다시 그렸다. 배치는 D2의 도형 크기와 이름표 규칙으로 계산하고, 그리기는 이 프로젝트의 크기로 했다. 두 모델이 어긋나서 선 끝이 도형에서 떨어지거나, 사람 모양의 이름표 때문에 선이 상자 아래쪽에 붙거나, 순서 그림 메시지가 참여자 옆으로 끌려가는 오류가 반복됐다. 오류마다 경로를 고치는 후처리를 더했고, 후처리끼리 다시 충돌했다. 그림 안쪽 방향을 바꿔 비율을 맞추는 일도 D2.js 안에서는 할 수 없었다. 문서 스킬은 구조 그림에 D2, 실험 차트에 Vega-Lite를 따로 써서 모양과 색이 두 벌이다.
선택지
| 선택지 | 장점 | 단점 |
|---|---|---|
| D2 원본과 D2.js 배치를 유지하고 후처리를 더한다 | d2 명령으로도 원본을 그린다 |
배치 모델과 그리기 모델이 계속 어긋나고, 후처리 규칙끼리 충돌한다 |
| D2가 만든 SVG를 그대로 쓰고 움직임만 얹는다 | 배치와 그리기가 일치한다 | 모양을 바꿀 수 없어 원하는 문서 그림 모양이 나오지 않는다 |
| Mermaid 문법과 Mermaid 배치를 쓴다 | 널리 알려진 문법이다 | 그림 종류마다 문법이 달라 규칙이 많고, 배치와 그리기가 Mermaid 안에 묶여 같은 어긋남이 생긴다 |
| 문법과 배치를 직접 맡고, 배치 계산만 elkjs에 맡긴다 | 도형 크기를 재는 코드와 그리는 코드가 같아 어긋남이 없다. 그림 종류와 차트를 한 문법으로 묶는다 | D2 호환이 없다. 순서 그림과 차트 배치를 직접 만든다 |
결정
문법과 배치를 직접 맡고, 층 배치와 직교 선 경로 계산만 elkjs(ELK layered)에 맡긴다. 가른 기준은 배치에 넘기는 도형 크기와 연결점이 그리는 도형과 같은지다. 이 선택지만 그 조건을 만족한다. 문법은 D2의 ->, 도형 이름, direction과 Mermaid의 첫 줄 그림 종류 선언을 빌려 와서 처음 보는 사람과 AI가 익숙하게 쓰게 한다.
2026-10-01에 elkjs 0.9로 세 가지를 확인했다.
- 한 번에 배치하면(
INCLUDE_CHILDREN) container 안의 방향 설정이 무시된다. D2.js가 안쪽 방향을 무시한 이유와 같다. - container마다 따로 배치하면(
SEPARATE_CHILDREN) 안쪽 방향이 지켜지고, container 경계의 연결점(port)을 거쳐 바깥 선과 안쪽 선이 모두 경로를 받는다. - container가 없는 그림은 줄 바꿈 배치(
elk.layered.wrapping.strategy)로 가로세로 비율이 19:1에서 1.4:1로 줄었다. container가 있으면 줄 바꿈이 동작하지 않았다.
결과
- 배치와 그리기가 같은 도형 크기와 연결점을 써서 선 끝 붙이기, 끝점 다시 놓기 같은 후처리가 없어진다.
- container마다 방향을 정해 그림 비율을 맞춘다.
- 구조 그림, 순서 그림, 상태 그림, 데이터 그림, 차트를 한 문법, 한 토큰, 한 재생기로 만든다.
- 기존 D2 원본은 이 도구로 그릴 수 없다. 새 문법으로 다시 쓴다.
- elkjs(EPL-2.0)에 의존한다. 코드를 옮겨 오지 않고 패키지로만 쓴다.
- 순서 그림 배치와 차트 배치를 직접 유지한다.
다시 볼 조건
- container 경계 연결점 방식이 실제 예제에서 선을 도형 위로 지나가게 만드는 경우가 그림 검사로 반복해서 잡힐 때
- elkjs가 유지되지 않거나, 같은 입력에 다른 좌표를 내서 다시 그린 그림이 바뀔 때