D2로 정적 다이어그램 그리기

결론부터

• D2는 요소와 연결을 텍스트로 적어 그림을 만드는 도구다. 이 사이트의 정적 관계도와 흐름도에 쓴다.
• 이 사이트는 빌드 때 SVG를 만들고 문법 오류를 확인하며, 이미지 확대 방식을 통일하려고 기존 Mermaid 통합을 D2로 바꿨다.
• Mermaid도 CLI로 미리 렌더할 수 있다. 선택 이유는 언어의 절대적 우열이 아니라 이 저장소의 작성·검증 방식에 있다.
• 빌드가 통과해도 잘못된 관계나 겹친 글자는 남을 수 있다. 그림을 읽고 의미와 가독성을 별도로 확인한다.

이 장에서 처음 나오는 말2개

다이어그램Diagram

요소 사이의 관계·방향·경계를 단순화해 보여 주는 그림.

D2

요소와 연결을 텍스트로 적어 다이어그램을 만드는 도구. 이 사이트의 정적 관계도에 쓴다.

글로 나열한 구성 요소를 한눈에 연결해 보고 싶을 때 다이어그램을 쓴다. 이 페이지는 D2 그림을 어떻게 읽고 요청하며, 왜 이 사이트가 Mermaid 대신 D2를 쓰는가에 답한다. 문법을 외우지 않아도 아래 그림을 읽고 AI에게 수정할 관계를 전달할 수 있다.

제품 화면의 위치·모양을 보여 주려면 이미지 사용 안내를 본다. D2는 화면을 재현하기보다 개념의 경계·연결·방향을 설명하는 데 쓴다.

관계를 알아야 하면 다이어그램을 쓴다

이 사이트는 D2라는 도구로 구성 요소와 연결을 그림으로 만든다. AI가 텍스트로 원본을 작성하므로 나중에 관계나 이름을 바꾸기 쉽다. D2 공식 소개에서 원본과 그림의 대응을 볼 수 있다.

다음은 이 사이트에서 문서가 발전하는 과정을 단순화한 그림이다. 검증을 마친 초안도 사람이 읽은 뒤 다시 수정될 수 있다는 점을 본다.

아래로 내려가는 선은 작성한 결과가 독자와 공유 대상으로 이어지는 흐름이다. 위로 돌아가는 선은 읽다가 생긴 의문을 다음 수정에 반영하는 흐름이다. AI의 검증 통과와 사람의 이해는 서로 다른 확인 단계다.

텍스트가 그림이 되는 과정

위 그림의 화살표 하나는 다음처럼 적을 수 있다. 전체 그림 중 한 연결을 발췌한 예다.

review: AI 의미 리뷰 · 기술 검증
reader: 사람 화면 확인
review -> reader: 결과 전달

review와 reader는 요소를 구별하는 이름이고, 콜론 뒤는 화면에 보일 말이다. ->가 방향을, 뒤의 결과 전달이 화살표의 뜻을 정한다. AI는 이 텍스트를 MDX 본문의 d2 코드 블록에 넣는다. 관계가 바뀌면 이미지 편집기 대신 원본 텍스트를 수정하고 다시 빌드한다.

D2는 Starlight의 내장 컴포넌트가 아니다. 이 사이트에서는 다음 도구들이 역할을 나눈다.

단계	맡는 도구	독자에게 보이는 결과
원본 작성	D2 문법	요소·경계·화살표를 텍스트로 기록
사이트 빌드	astro-d2와 D2 실행 파일	코드 블록을 SVG 이미지로 변환
페이지 열기	브라우저의 이미지 표시	완성된 그림을 바로 표시
그림 누르기	starlight-image-zoom	확대 dialog에서 자세히 읽기

astro-d2는 Astro 통합이다. 저장소 설정은 이를 starlight()보다 먼저 등록하고, 기본적으로 외부 SVG 이미지로 출력한다. 그림을 그리는 D2 엔진은 브라우저에서 실행하지 않지만, 클릭 확대에는 별도 스크립트를 사용한다.

Mermaid에서 D2로 — 왜 갈아탔나

이 저장소는 예전에 Mermaid로 다이어그램을 작성했다. 당시 통합은 페이지를 연 브라우저에서 그림을 만들었기 때문에, 사이트 빌드가 끝나도 그림의 문법 오류가 뒤늦게 드러날 수 있었다. AI가 여러 페이지를 고치는 작업에서는 배포 전에 오류를 발견하고 완성된 이미지를 확인하는 흐름이 필요했다. 2026년 8월에 기존 그림을 D2로 옮기고 Mermaid 통합을 제거했다.

판단 기준	이 사이트의 이전 Mermaid 통합	현재 D2 통합
그림을 만드는 시점	페이지를 여는 브라우저에서 렌더	사이트 빌드 때 SVG 생성
문법 오류 확인	빌드 외에 브라우저 렌더 확인 필요	D2 변환 실패가 빌드 오류로 드러남
확대 방식	다이어그램용 표시·확대 처리를 별도로 관리	본문 이미지와 같은 확대 플러그인 사용
AI의 수정 결과 확인	브라우저에 그려진 결과를 확인	생성한 SVG·PNG를 빌드·브라우저와 별도로 검사 가능

이 비교는 이 저장소에서 사용한 통합 방식의 비교다. Mermaid CLI도 SVG·PNG·PDF를 미리 생성할 수 있으므로, “Mermaid는 빌드 때 검사할 수 없다”거나 “D2만 정적 그림을 만들 수 있다”는 뜻은 아니다. 두 도구 모두 텍스트 원본을 Git에서 관리할 수 있다.

이 사이트는 D2로 전환하면서 빌드 검증·이미지 확대·색과 배치 규칙을 한 방식으로 정리했다. 현재는 D2 실행 파일의 버전도 고정해 로컬과 배포 환경이 같은 도구로 그리게 한다. 이미 Mermaid의 문법과 사전 렌더가 잘 갖춰진 다른 문서라면 그 방식을 유지할 수도 있다. D2가 더 빠르거나 AI가 더 정확하게 작성한다고 실측한 것은 아니다.

자동 배치에도 확인할 부분이 있다

D2를 골랐다고 그림이 저절로 읽기 좋아지는 것은 아니다. 이 사이트의 기본 배치 엔진은 ELK이고, 넓은 그림은 본문에 맞춰 축소되어 글자가 작아질 수 있다. 세로로 배치하거나 질문별로 그림을 나누고, 필요할 때 눌러 확대해서 읽는다.

색은 성공·실패·주의·핵심 대상처럼 사이트에서 정한 의미로 사용하고, 라벨에도 뜻을 적는다. SVG 이미지 안의 노드를 눌러 상태를 바꾸는 방식은 이 사이트의 D2 사용 범위에 포함되지 않는다. 단계마다 전달 값과 보관 상태를 바꿔 읽으려면 LearningFlow를 쓴다.

AI에게 그림을 요청한다

그림의 모양보다 관계와 질문을 먼저 준다.

이 페이지의 로그인 설명을 D2 다이어그램으로 보완해줘.
브라우저·앱 서버·인증 서버의 경계를 구분하고,
누가 요청하고 어떤 값을 응답하는지 화살표에 적어줘.
그림 아래에는 읽을 순서와 이번 예제에서 생략한 조건을 설명해줘.
본문 폭에서 글자가 잘 읽히도록 배치하고 렌더 결과를 확인해줘.

그림 하나에 모든 예외를 넣을 필요는 없다. 정상 흐름을 먼저 읽게 하고, 실패 경로가 별도 질문이라면 그림이나 절을 나눠 달라고 요청한다.

그림을 보고 피드백한다

확인할 것	피드백 예
화살표 방향과 의미	이 화살표가 요청인지 응답인지 모르겠어. 보내는 값과 방향을 분명히 해줘
구성 요소의 경계	브라우저와 서버 내부 데이터가 섞여 보여. 어디에 보관되는지 구분해줘
읽는 순서	어디부터 따라가야 할지 모르겠어. 출발점과 관찰할 순서를 설명해줘
글자와 배치	확대해야만 라벨이 읽혀. 그림을 나누거나 세로로 배치해줘
본문과 일치	본문은 검증 후 저장한다고 하는데 그림에는 검증이 없어. 근거와 대조해 맞춰줘

이 사이트의 그림과 본문 이미지는 눌러서 확대할 수 있다. 확대가 가능해도 기본 화면에서 핵심 관계는 읽혀야 한다. 색만으로 성공·실패를 구별하지 말고 라벨에도 의미가 드러나게 한다.

이해 확인

그림의 빌드가 성공했는데 요청 화살표가 거꾸로라면 검증이 끝난 것일까? 문법은 유효하지만 설명은 틀릴 수 있다. 본문의 요청 주체·수신자와 화살표를 대조해야 한다. 글자가 겹치거나 지나치게 작다면 배치를 바꾸고 렌더 결과를 다시 확인한다.

단계마다 남는 값이 궁금하면

전체 관계가 보여도 “지금 이 순간 브라우저가 무엇을 갖고 있는가?”는 한 장의 그림으로 따라가기 어려울 수 있다. 그때는 LearningFlow로 메시지와 보관 상태를 한 단계씩 읽는다.

D2 문법·색·배치와 정적 렌더 확인은 AI가 D2 작성 지침을 따라 처리한다. 사람은 그림이 자신의 질문에 답하는지를 보고 피드백하면 된다.

LearningFlow로 단계별 흐름 읽기실제 예제를 조작하며 전달 값과 보관 상태를 확인한다.