코드 위키는 mermaid를 얼마나 쓸까 — React 위키 115개·Express 위키 221개 실측과 의미

코드 위키 도구들이 다이어그램을 많이 쓴다는 얘기는 이전 글에서 했다. "얼마나 많이?"에 답해 본 적은 없었다. 그래서 직접 세 보았다.

2026-05 기준 deepwiki.com/facebook/react 위키는 sub-page 34개로 구성되어 있고 그 안에 mermaid 다이어그램 115개가 들어가 있다(페이지당 평균 약 3.4개). expressjs/express 위키는 32 페이지에 221개(페이지당 평균 약 6.9개). DeepWiki는 SPA 방식이라 한 URL에 위키 전체 페이로드가 같이 실려 오는데, 그 페이로드를 그대로 grep해서 ```mermaid 블록을 센 결과다.

한 위키 전체에 다이어그램 100~200개라는 게 처음엔 비현실적으로 들리지만, 큰 코드 베이스를 설명할 때 흔한 분량이다. 기술서 한 권에 그림 200~500장이 흔하고, 위키 한 묶음에 100~200개면 그보다 적은 편이다.

이 글은 그 mermaid가 무엇이고, 어떻게 문서에 들어가고, 왜 그게 PNG·SVG가 아닌가, 사람과 AI에게 어떻게 다른 가치를 주는가를 풀어 본다.

1. mermaid가 뭔지부터

mermaid는 "텍스트로 다이어그램을 그리는 문법"이다. 마크다운 안에 ```mermaid 코드 블록을 두면, 페이지에 함께 로드된 mermaid.js 라이브러리가 그 텍스트를 파싱해서 SVG로 렌더링한다. 즉 변환 주체는 브라우저 자체가 아니라 페이지가 불러온 자바스크립트 라이브러리다. GitHub README·GitLab·Notion 같은 곳에서도 같은 라이브러리(또는 호환 렌더러)를 끼워 표준처럼 지원한다.

가장 단순한 예 — 다음 텍스트가

```mermaid
graph LR
  Client --> Server
  Server --> Database
```

이렇게 렌더링되는 식이다 — "Client → Server → Database"가 화살표 2개의 흐름도로. 코드를 짜듯이 다이어그램을 짜는 방식이다. PowerPoint로 그릴 일을 텍스트로 처리할 수 있고, git diff로 변경 이력도 따라잡힌다.

2. 실제 사용량 — 위키 한 묶음에 100~200개

2026-05-17 직접 조사한 데이터다. 각 위키는 sub-page 여러 개로 구성돼 있고, 아래 숫자는 그 sub-page 전체에 박힌 mermaid 블록의 합계다.

다이어그램 설명. Express 위키가 React 위키보다 다이어그램이 많은 이유는 페이지 수가 비슷한데(32 vs 34) 흐름 중심이라는 차이 때문이다 — Express는 미들웨어·라우터·핸들러 흐름을 mermaid로 풀어내는 경우가 많고, React는 같은 분량의 정보를 텍스트·코드 인용에 더 많이 의지한다. "코드 베이스가 클수록 다이어그램이 많다"가 아니라 "흐름이 많을수록 다이어그램이 많다"는 게 핵심 패턴이다.

3. 어떤 유형의 다이어그램이 많은가

React 위키 전체(34 페이지)에 박힌 115개 다이어그램을 유형별로 분류했다.

다이어그램 설명. 압도적으로 많은 게 `graph` 변형(TB·TD·LR 합쳐서 96개, 전체의 83%)이다. 박스를 화살표로 잇는 가장 단순한 표현이 그만큼 자주 쓰인다는 뜻. 그 뒤로 sequence(호출 순서), state(상태 전이), flowchart(조건부 흐름)가 따라온다. 이 다섯 유형이 거의 모든 코드 설명을 커버한다.

4. 어떻게 문서에 들어가나 — base64가 아니라 raw markdown

다이어그램을 문서에 박는 방식은 크게 두 가지다. 각각의 의미·장단점이 다르다.

다이어그램 설명. DeepWiki·CodeWiki·deepwiki-open은 모두 방식 B(raw mermaid + 클라이언트 렌더링)를 쓴다. 마크다운 원문에 ```mermaid 블록을 그대로 두고, 페이지 로드 시 함께 실리는 mermaid.js 라이브러리가 그 텍스트를 파싱해 SVG로 그려 낸다. 다이어그램이 많을수록 방식 B가 결정적으로 유리하다 — 100개 PNG라면 본문이 수 MB가 되지만, mermaid 텍스트 100개는 수십 KB로 끝난다.

5. 사람에게 mermaid가 좋은 이유 — 그림과 코드의 중간 자리

같은 정보를 PowerPoint 그림으로 그릴 수도 있고, 글로 풀어 설명할 수도 있다. mermaid는 그 사이에 있다.

• 그림보다 빠르게 만든다 — 박스 5개에 화살표 5개짜리 흐름도를 PowerPoint로 그리는 데 5분, mermaid로는 30초. 자동 생성도 가능.
• 글보다 빠르게 이해된다 — "Request가 Express로 들어와서 미들웨어 체인을 거쳐 라우터에 도착하고 핸들러가 응답을 만든다"를 텍스트로 읽는 데 10초, 그림으로는 2초.
• 버전 관리가 자연스럽다 — git diff가 의미 있는 한 줄 변경으로 보인다. PowerPoint 파일은 한 글자 바뀌어도 바이너리 전체가 새로 들어간다.
• 수정이 쉽다 — 노드 이름 하나 바꾸려면 텍스트 한 단어만 고치면 끝. 그림 도구는 노드를 클릭해서 텍스트 편집해야 한다.

코드 위키처럼 "자동 생성 + 자동 갱신"이 핵심인 도구에서 mermaid는 사실상 유일하게 합리적인 선택이다. LLM에게 PNG를 만들라고 시키면 매번 다르게 그리지만(환각의 위험), mermaid 텍스트를 만들라고 시키면 일관성이 유지된다.

6. AI에게 mermaid가 결정적인 이유

여기가 진짜 흥미로운 지점이다. mermaid는 사람에게도 좋고 AI에게도 좋은 드문 형식이다.

다이어그램 설명. 같은 다이어그램이 PNG로 박혀 있으면 AI에겐 의미 없는 픽셀 덩어리다. 반면 mermaid로 박혀 있으면 그래프 구조를 텍스트로 직접 읽어 추론할 수 있다. 코드 위키가 mermaid를 선택한 진짜 이유는 AI 친화성 때문이라고 봐도 무리가 없다.

구체적으로 AI 에이전트가 이런 식으로 활용한다.

• 구조 질문에 즉답: "이 시스템에서 인증은 어디서 하나" → mermaid 그래프를 보고 "Middleware 레이어의 auth 노드"라고 답.
• 변경 영향 분석: "Router를 바꾸면 뭐가 깨지나" → mermaid에서 Router의 inbound/outbound edge를 읽어 영향 범위 추정.
• 새 컴포넌트 추가 제안: "여기에 캐시 레이어를 넣고 싶다" → 기존 mermaid를 보고 어디에 넣어야 자연스러운지 추론.
• 다이어그램 자체 수정: "위 mermaid에 X 노드 추가해 줘" → 텍스트 한두 줄 추가로 답. PNG였다면 불가능.

이게 단순한 가독성 차이가 아니라 AI가 그 다이어그램을 "활용 가능한 데이터"로 다룰 수 있느냐 없느냐의 차이다. PNG는 장식, mermaid는 자료.

7. 그래서 어떻게 박혀 있는가 — 실제 패턴

DeepWiki 위키 페이지를 들여다보면 다이어그램 박는 패턴이 일관적이다.

## High-Level Architecture

**Diagram: Overall System Architecture**

```mermaid
graph TB
    subgraph BuildSystem["Build System (scripts/rollup/)"]
        Bundles["bundles.js<br/>Bundle Definitions"]
        Build["build.js<br/>Rollup Pipeline"]
    end
    subgraph Packages["Core Packages"]
        ReactPkg["packages/react"]
        ReactDOM["packages/react-dom"]
    end
    Build --> ReactPkg
    Build --> ReactDOM
```

The build system in `scripts/rollup/` orchestrates ...

패턴 정리:

1. 섹션 헤더(`## High-Level Architecture`)
2. 다이어그램 라벨(`**Diagram: Overall System Architecture**`) — 무엇을 보여 줄지 한 줄 설명
3. ```mermaid 블록 — 다이어그램 본체
4. 본문 paragraph — 다이어그램 옆에 설명 글

라벨이 다이어그램 위에 붙는다는 게 중요한 디테일이다. 라벨이 있으면 AI가 "이 그림이 무엇을 보여 주는가"를 다이어그램 내용보다 먼저 알 수 있고, 사람도 스크롤하다가 다이어그램이 뭔지 한 줄로 파악할 수 있다. 작은 차이처럼 보이지만 다이어그램이 100개 넘게 박힌 페이지에선 이 라벨이 페이지 탐색의 핵심이 된다.

마무리 — 다이어그램을 어떻게 저장하느냐가 시스템 친화성을 결정한다

다이어그램은 코드 위키의 "장식"이 아니다. "코드를 어떻게 설명할지의 핵심 표현 수단"이고, 그 표현을 PNG로 굳히느냐 텍스트로 두느냐가 시스템 전체의 친화성을 결정한다.

mermaid가 코드 위키 표준이 된 건 단순히 "예쁘게 그리려고"가 아니다. "자동 생성에 잘 맞고, 수정이 쉽고, 사람도 읽고 AI도 읽는다"는 네 가지를 동시에 만족하는 유일한 형식이기 때문이다. 다른 형식을 선택했다면 — 가령 모든 다이어그램을 LLM이 PNG로 그려 base64로 박았다면 — 코드 위키의 모든 자동화·갱신·AI 친화성이 무너졌을 것이다.

본인 프로젝트의 docs에서 다이어그램을 그릴 일이 있다면 mermaid를 우선 시도해 보면 좋겠다. 화려한 그림 도구가 줄 수 없는 "사람과 AI가 같은 자료를 같이 다룬다"는 효과가 의외로 크다. 다이어그램 200개짜리 위키를 매일 갱신할 수 있는 비결도 결국 거기에 있다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.