Asciidoctor Diagram은 AsciiDoc 문서 안의 텍스트로 다이어그램을 정의하고, 변환 과정에서 이미지로 생성하는 확장 기능입니다. 이 장에서는 Asciidoctor Diagram이 지원하는 Mermaid를 사용해 흐름도, 시퀀스 다이어그램, 클래스 다이어그램을 작성합니다.

Mermaid 블록은 mermaid 형식, 생성할 이미지 이름인 target, 출력 형식인 `format`으로 구성합니다. HTML, EPUB, PDF에서 함께 사용할 수 있도록 이 장의 예제는 모두 PNG로 출력합니다.

[mermaid, target=output-name, format=png]
----
Mermaid 문법으로 작성한 다이어그램
----

Asciidoctor Diagram은 Mermaid 블록을 이미지로 바꿀 때 mmdc 실행 파일을 호출합니다. Node.js는 NVM으로 관리하고 Mermaid CLI는 `npm install --global @mermaid-js/mermaid-cli@latest`로 설치합니다. Google Chrome은 JavaScript, DOM, 폰트와 레이아웃을 실제로 렌더링하는 브라우저이고, Mermaid CLI가 의존하는 Puppeteer는 Chrome을 headless 모드로 제어해 결과를 이미지로 내보냅니다. Chrome과 Puppeteer는 대체 관계가 아니므로 둘 다 필요합니다. Puppeteer의 별도 Chrome 다운로드를 생략할 때는 `PUPPETEER_EXECUTABLE_PATH`로 사용할 Google Chrome 실행 파일을 지정합니다. 변환을 시작하기 전에 `mmdc`가 `PATH`에서 실행되는지 확인합니다.

흐름도

흐름도는 작업 단계와 조건에 따른 분기를 표현합니다. flowchart 뒤에 방향을 지정하고, 노드를 화살표로 연결합니다.

[mermaid, target=mermaid-flowchart, format=png]
----
flowchart LR
    A[Write AsciiDoc] --> B{Preview correct?}
    B -->|Yes| C[Publish]
    B -->|No| A
----
mermaid flowchart

`LR`은 노드를 왼쪽에서 오른쪽으로 배치합니다. 대괄호는 일반 작업 노드를, 중괄호는 조건 노드를 만들며, `|Yes|`와 `|No|`는 분기 레이블을 표시합니다.

시퀀스 다이어그램

시퀀스 다이어그램은 참여자 사이에서 메시지가 오가는 순서를 위에서 아래로 보여 줍니다. `actor`와 `participant`로 참여자를 선언하고 화살표로 요청과 응답을 구분합니다.

[mermaid, target=mermaid-sequence, format=png]
----
sequenceDiagram
    actor Reader
    participant Site as Docs site
    participant Build as Build pipeline

    Reader->>Site: Request page
    Site->>Build: Request diagram
    Build-->>Site: Return image
    Site-->>Reader: Show document
----
mermaid sequence

실선 화살표 →>`는 요청을, 점선 화살표 `-→>`는 응답을 나타냅니다. `as 뒤에 표시 이름을 지정하면 메시지 정의에서는 짧은 참여자 이름을 계속 사용할 수 있습니다.

클래스 다이어그램

클래스 다이어그램은 클래스의 속성과 메서드, 클래스 사이의 관계를 표현합니다. 중괄호 안에 멤버를 작성하고 관계 기호 양쪽에 클래스 이름을 배치합니다.

[mermaid, target=mermaid-class, format=png]
----
classDiagram
    class Document {
        +String title
        +build()
    }
    class Diagram {
        +String format
        +render()
    }

    Document "1" *-- "many" Diagram : contains
----
mermaid class

멤버 앞의 더하기 기호는 공개 범위를 나타냅니다. `*--`는 합성 관계를 나타내며, 양쪽의 `1`과 `many`는 관계의 개수를 설명합니다.

이 장의 예제는 Asciidoctor Diagram의 공통 블록 문법과 Mermaid 지원 문서를 바탕으로 작성했습니다.

참고 자료

이 페이지가 도움이 되었나요?