.mmd 파일 여는 방법

보이는 증상

No diagram type detected matching given configuration for text: ```mermaid

원인

Markdown 파일이나 채팅에서 다이어그램을 복사할 때 펜스까지 함께 가져왔습니다. 백틱 세 개는 Markdown이지 Mermaid가 아니므로 파서가 다이어그램 본체에 닿지 못합니다.

해결

맨 앞의 ```mermaid 줄과 맨 뒤의 ``` 줄을 지웁니다. 파일은 다이어그램 키워드로 시작해야 합니다.

```mermaid
flowchart TD
    A[시작] --> B[끝]
```

flowchart TD
    A[시작] --> B[끝]

보이는 증상

Parse error, 끝부분: got 'PS'

오류 끝부분: got 'PS'

원인

노드 레이블 안에 반각 여는 소괄호가 있습니다. Mermaid에서 소괄호는 모양 문법이라 `A(글자)`는 둥근 노드를 뜻하고, 그래서 대괄호 안의 맨 괄호는 모양의 시작으로 읽힙니다.

해결

레이블 전체를 큰따옴표로 감쌉니다. 따옴표 안은 괄호를 포함해 모두 글자로 취급됩니다.

flowchart TD
    A[결제 호출(주문)] --> B[완료]

flowchart TD
    A["결제 호출(주문)"] --> B[완료]

보이는 증상

노드 ID를 적은 줄에서 Parse error

원인

노드 ID 안에 띄어쓰기가 있습니다. 한국어에서 특히 자주 생깁니다. 중국어나 일본어는 단어를 띄어 쓰지 않아 이 문제가 아예 없지만, 한국어는 띄어 쓰고 자연스러운 이름은 대부분 두 어절 이상입니다. ID는 화살표 앞의 토큰이라 공백이 그것을 끊고, 놓을 데 없는 단어가 하나 남습니다.

해결

ID는 붙여 쓴 한 덩어리로 하고, 읽을 글자는 대괄호 레이블에 넣습니다. 한글 자체는 ID로 문제없이 쓸 수 있습니다.

flowchart TD
    인증 서버 --> db[사용자 DB]

flowchart TD
    인증[인증 서버] --> db[사용자 DB]

보이는 증상

Parse error, 끝부분: got 'STR'

오류 끝부분: got 'STR'

원인

노드 레이블 도중에 반각 큰따옴표가 있습니다. 파서는 그것을 문자열의 시작으로 보고, 닫는 따옴표를 기대한 자리에서 레이블의 닫는 대괄호를 만납니다.

해결

레이블 전체를 큰따옴표로 감싼 다음 안에서는 작은따옴표나 낫표를 씁니다. HTML 실체 참조 #quot;로도 됩니다.

flowchart TD
    A[상태는 "보류"] --> B[완료]

flowchart TD
    A["상태는 '보류'"] --> B[완료]

보이는 증상

Parse error, 끝부분: got 'end'

오류 끝부분: got 'end'

원인

`end`를 노드 ID로 썼습니다. 소문자 `end`는 서브그래프를 닫으므로, 노드가 있어야 할 자리에 블록의 끝이 나타난 셈입니다. 영어 예제를 따라가다 마지막 노드만 `end`가 되는 일이 자주 있습니다.

해결

첫 글자를 대문자로 하거나 다른 ID를 주고 그 단어를 레이블에 넣습니다. `종료`는 문제없습니다.

flowchart TD
    A[시작] --> end

flowchart TD
    A[시작] --> 종료[완료]

보이는 증상

그려지는데 상태 다이어그램에서 상태 하나가 둘로 갈라져 있다

원인

상태 ID 안의 띄어쓰기입니다. 순서도와 달리 상태 다이어그램은 이것을 거부하지 않습니다. 어절마다 별개의 상자를 만들어 그대로 그려 버립니다. 실측: `[*] --> 결제 대기`는 「결제」와 「대기」 두 상태가 되고, 화살표에 걸리는 것은 앞의 것뿐입니다. 한국어의 자연스러운 상태 이름은 거의 다 두 어절이라 이 오류가 계속 생기는데, 생겼다는 신호가 전혀 없습니다.

해결

`state "표시 이름" as ID`로 선언하고 이후로는 ID로만 참조합니다.

stateDiagram-v2
    [*] --> 결제 대기
    결제 대기 --> 종료

stateDiagram-v2
    state "결제 대기" as 결제대기
    [*] --> 결제대기
    결제대기 --> 종료

보이는 증상

그려지는데 ER 다이어그램에 적은 적 없는 개체가 있다

원인

관계 레이블에 띄어쓰기가 있는데 따옴표가 없습니다. 한국어에서 관계는 「주문을 한다」처럼 두 어절 이상이 자연스러워서 자주 걸립니다. Mermaid는 오류를 내지 않고 첫 공백에서 레이블을 끊은 뒤 남은 어절을 빈 개체로 만듭니다.

해결

띄어쓰기가 들어간 관계 레이블은 반드시 따옴표로 감쌉니다. 한국어에서는 사실상 항상입니다.

erDiagram
    고객 ||--o{ 주문 : 주문을 한다

erDiagram
    고객 ||--o{ 주문 : "주문을 한다"

보이는 증상

No diagram type detected matching given configuration for text: sequencediagram

원인

다이어그램 키워드의 철자나 대소문자가 틀렸습니다. Mermaid의 키워드는 대소문자를 구분합니다. sequenceDiagram은 되고 sequencediagram은 안 됩니다. stateDiagram-v2와 erDiagram도 마찬가지입니다.

해결

대소문자를 고칩니다. 참고로 `graph`는 `flowchart`의 옛 이름으로 지금도 받아들여지므로 그쪽은 원인이 아닙니다.

sequencediagram
    고객->>API: 주문 전송

sequenceDiagram
    고객->>API: 주문 전송

보이는 증상

세로줄 사이 간선 레이블에서 Parse error

원인

간선 레이블 안에 반각 소괄호가 있습니다. `|…|` 레이블에도 노드 레이블과 같은 제약이 걸려서, 거기서도 괄호는 글자가 아니라 문법입니다.

해결

간선 레이블도 따옴표로 감쌉니다.

flowchart TD
    A -->|예 (항상)| B

flowchart TD
    A -->|"예 (항상)"| B

보이는 증상

다이어그램의 마지막 줄에서 Parse error가 보고된다

원인

열어 놓고 닫지 않은 블록이 있습니다. alt, opt, loop, par, subgraph는 모두 짝이 되는 `end`가 필요합니다. Mermaid는 입력을 다 읽은 시점에 실패를 보고하므로 줄 번호가 닫지 않은 블록이 아니라 파일의 끝을 가리킵니다.

해결

블록을 연 수와 `end`의 수를 세어 봅니다. 오류 줄이 마지막 줄이면 거의 항상 이것입니다.

sequenceDiagram
    고객->>API: 주문 전송
    alt 재고 있음
        API-->>고객: 접수 완료

sequenceDiagram
    고객->>API: 주문 전송
    alt 재고 있음
        API-->>고객: 접수 완료
    end

보이는 증상

Lexical error on line 1. Unrecognized text.

원인

다이어그램 키워드 뒤의 방향 지정이 잘못됐습니다. 순서도가 받는 것은 TB, TD, BT, LR, RL뿐이고, 그 밖의 것은 노드를 읽기도 전에 어휘 분석에서 실패합니다.

해결

다섯 개 중 하나를 씁니다. TD와 LR이면 거의 다 됩니다.

flowchart XY
    A --> B

flowchart TD
    A --> B

보이는 증상

여기서는 그려지는데 GitLab이나 Confluence, 오래된 도구에서는 안 된다

원인

버전 차이입니다. 이 뷰어는 Mermaid 11.12.2로 돌아갑니다. GitLab.com은 버전 10을 명시하고 있고, 사내 위키는 몇 년씩 뒤처져 있는 일이 드물지 않습니다. 상대 쪽 버전보다 나중에 들어온 문법은 여기서는 통과하고 저기서는 실패합니다.

해결

상대 렌더러에 버전을 물어보세요. 다이어그램 안에 info라는 한 단어만 적으면 Mermaid가 자기 버전 번호를 그립니다. 릴리스 노트를 읽는 것보다 빠릅니다.

info