다이어그램

개요

Quarto는 Mermaid와 Graphviz 다이어그램을 기본으로 임베드할 수 있습니다. 이를 통해 마크다운에서 영감을 받은 단순한 텍스트 구문으로 순서도, 순차 다이어그램, 상태 다이어그램, 간트 차트 등을 작성할 수 있습니다.

예를 들어 다음과 같이 Mermaid로 만든 순서도를 임베드할 수 있습니다.

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

위에서 보았듯이 Mermaid 다이어그램은 {mermaid} 실행 셀을 사용해 임베드합니다. Graphviz 다이어그램은 {dot} 실행 셀을 사용하며, 셀 옵션을 넣을 때 구문이 약간 다릅니다. {mermaid}는 %%|, {dot}은 //|를 사용합니다.

Note

pdf, docx 같은 출력 형식으로 인쇄하려면 고품질 PNG를 만들기 위해 Chrome 또는 Edge 브라우저가 필요합니다. Quarto는 시스템에 설치된 Chrome/Edge를 자동으로 사용하거나, 둘 다 없다면 경량 라이브러리 버전의 Chrome을 사용할 수 있습니다(자세한 내용은 아래 Chrome 설치 참조).

Mermaid

Mermaid는 Markdown과 비슷한 텍스트 정의와 렌더러를 사용해 복잡한 다이어그램을 만들고 수정하는 JavaScript 기반 다이어그램/차트 도구입니다.

Mermaid 다이어그램은 주석 구문으로 %%를 사용하므로 셀 옵션은 %%|로 선언합니다. 셀 옵션은 다이어그램 코드 청크 시작 직후에 위치해야 합니다.

위에서는 Mermaid로 만든 순서도를 살펴보았습니다. 아래는 {mermaid} 실행 셀로 임베드한 시퀀스 다이어그램입니다.

```{mermaid}
sequenceDiagram
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
    John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
    John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

Mermaid 출력은 대상 형식(예: HTML vs. 인쇄 기반)에 따라 달라집니다. 자세한 내용은 아래 Mermaid 형식 섹션을 참고하세요.

Mermaid 사용법을 더 배우려면 Mermaid 웹사이트나 Mermaid 창작자가 집필한 Mermaid 책을 확인하세요.

Graphviz

Graphviz 레이아웃 프로그램은 간단한 텍스트 언어로 그래프를 설명하면 다양한 형식의 다이어그램을 생성합니다. 색상, 글꼴, 표 형식 노드 레이아웃, 선 스타일, 하이퍼링크, 사용자 정의 모양 등 실용적인 다이어그램에 필요한 기능을 풍부하게 제공합니다.

Graphviz 다이어그램은 주석 구문으로 //를 사용하므로 셀 옵션은 //|로 선언합니다. 셀 옵션은 다이어그램 코드 청크 시작 직후에 위치해야 합니다.

예를 들어 다음은 Graphviz로 만든 단순한 무방향 그래프입니다.

```{dot}
graph G {
  layout=neato
  run -- intr;
  intr -- runbl;
  runbl -- run;
  run -- kernel;
  kernel -- zombie;
  kernel -- sleep;
  kernel -- runmem;
  sleep -- swap;
  swap -- runswap;
  runswap -- new;
  runswap -- runmem;
  new -- runmem;
  sleep -- runmem;
}
```

Graphviz에 대해 더 알아보려면 Graphviz 웹사이트, 간단한 Graphviz 예제 모음, Graphviz 갤러리를 참고하세요.

작성 도구

다이어그램 작성 생산성을 높여 주는 도구는 다양합니다.

Mermaid Live Editor는 Mermaid 다이어그램을 실시간으로 편집하고 미리 볼 수 있는 온라인 도구입니다.
Graphviz Online은 Graphviz 다이어그램을 편집할 수 있는 유사한 도구를 제공합니다.
RStudio는 DiagrammeR 패키지의 도움으로 .mmd, .dot 파일 편집과 미리 보기를 지원합니다.
VS Code 및 Positron용 Quarto 확장( OpenVSX, Microsoft Marketplace에서 제공)은 .qmd, .mmd, .dot 파일에 임베드된 다이어그램을 실시간으로 미리 볼 수 있습니다.

상호 참조

다이어그램을 그림처럼 취급할 수 있습니다. 예를 들어 앞선 다이어그램에 다음 그림 옵션을 추가한다고 가정해 보겠습니다.

```{dot}
//| label: fig-simple
//| fig-cap: "This is a simple graphviz graph."
```

그러면 다음과 같은 결과를 얻습니다.

Figure 1: This is a simple graphviz graph.

다이어그램을 다음과 같이 상호 참조할 수 있습니다.

@fig-simple

Div 문법으로 다이어그램에 크로스레퍼런스를 걸려면 그림과 동일하게 처리하면 됩니다. 예를 들어 Figure 2 는 다음과 같이 작성합니다.

::: {#fig-simple}

```{dot}
graph {
  A -- B
}
```

This is a simple graphviz graph
:::

Figure 2: This is a simple graphviz graph

다이어그램에 그림과는 다른 레이블·번호 체계를 부여하고 싶다면 사용자 정의 크로스레퍼런스 타입을 정의해 보세요.

파일 포함

.dot 또는 .mmd 파일에서 다이어그램을 따로 편집한 뒤 .qmd 문서에서 참조하는 편이 더 편할 수도 있습니다. 이때 Mermaid 또는 Graphviz 셀에 file 옵션을 추가하면 됩니다.

예를 들어 다음은 본문에 넣기에는 너무 복잡한 다이어그램을 파일로 포함한 사례입니다.

```{dot}
//| label: fig-linux-kernel
//| fig-cap: "A diagram of the Linux kernel."
//| file: linux-kernel-diagram.dot
```

Figure 3: A diagram of the Linux kernel.

file을 사용할 때도 label과 fig-cap 속성은 그대로 작동합니다.

크기 조정

기본적으로 다이어그램은 고유 크기로 렌더링됩니다(현재 문서의 기본 그림 크기에 맞춰 늘어나지 않습니다). HTML 출력에서는 다이어그램의 폭이 페이지 열을 넘지 않도록 반응형으로 처리됩니다. 이는 이미지나 동적 JavaScript 위젯과 동일한 방식입니다.

반응형 크기 조정을 사용하지 않으려면 fig-responsive: false 옵션을 지정하세요. fig-width, fig-height로 명시적인 크기를 지정할 수도 있습니다. 예를 들어 요소가 몇 개 없어서 Mermaid 다이어그램을 약간 크게 만들고 싶다면 다음과 같이 작성합니다.

```{mermaid}
%%| fig-width: 6.5
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}

Mermaid 형식

문서에 Mermaid 다이어그램을 포함하면 출력 형식에 따라 다이어그램 형식이 자동으로 결정됩니다.

형식	출력
HTML (`html`, `revealjs` 등)	Mermaid 기본(JavaScript)
GitHub Flavored Markdown (`gfm`)	Mermaid 코드 블록
기타 형식 (`pdf`, `docx` 등)	PNG 이미지

JavaScript를 지원하는 출력 형식에서는 기본적으로 Mermaid 네이티브 형식이 사용됩니다.

format: gfm을 사용할 때는 다이어그램이 일반 mermaid 코드 블록으로 출력됩니다. GitHub와 GitLab이 Mermaid 코드 블록을 자동으로 렌더링하기 때문입니다.

Mermaid를 별도로 처리하지 않거나 JavaScript 런타임이 없는 형식(pdf, docx, epub 등)은 Chrome을 사용해 PNG 이미지를 생성합니다.

mermaid-format 옵션으로 기본 동작을 변경할 수도 있습니다. 예를 들어 다음과 같이 지정하면 됩니다.

---
format:
  gfm:
    mermaid-format: png
---

mermaid-format에 지정할 수 있는 값은 js, png, svg입니다.

LaTeX을 통한 PDF 출력에서 SVG 형식 제한 사항

LaTeX 기반 형식으로 렌더링할 때 mermaid-format: svg를 사용하면 추가 도구가 필요하고 렌더링 문제가 발생할 수 있습니다.

설치 필요: Quarto가 SVG를 PDF로 변환해 LaTeX에 포함할 수 있도록 시스템 PATH에 rsvg-convert 또는 inkscape가 있어야 합니다.
렌더링 문제 가능: 여러 줄 레이블을 포함한 다이어그램에서 텍스트가 잘릴 수 있습니다.
권장 사항: LaTeX PDF 출력에서는 기본값인 mermaid-format: png를 유지하세요.

설치 방법과 Inkscape 구성 등 자세한 내용은 SVG 이미지를 참고하세요.

Mermaid 테마

다음 섹션에서는 Mermaid 다이어그램 색상 테마를 제어하는 방법을 설명합니다.

현재 문서 테마 사용
YAML 옵션을 이용해 Mermaid 기본 테마 사용
SCSS/CSS 변수를 이용한 커스터마이징

Mermaid 다이어그램 기본 색상

기본 테마를 포함한 Quarto bootswatch 기본 테마 또는 동일한 SCSS 변수를 사용하는 사용자 정의 테마를 사용하면 Mermaid 다이어그램도 자동으로 해당 테마를 따릅니다.

다음 예시는 Quarto 내장 bootswatch 테마로 이를 보여 줍니다.

A screenshot of a Mermaid flowchart in a document using bootswatch's Darkly theme.

A screenshot of a Mermaid flowchart in a document using bootswatch's Sandstone theme.

A screenshot of a Mermaid flowchart in a document using bootswatch's Vapor theme.

Bootstrap SCSS 변수와 Quarto Mermaid SCSS 변수 간 대응 관계, 수정 방법은 아래 Mermaid 테마 커스터마이징 섹션을 참고하세요.

Mermaid 기본 테마 사용

Mermaid가 제공하는 테마를 사용하려면 YAML front matter에서 mermaid 옵션을 설정하면 됩니다.

format:
  html:
    mermaid:
      theme: forest

Mermaid에서 제공하는 테마는 default, dark, forest, neutral입니다.

A screenshot of a Mermaid flowchart using the Mermaid's default theme.

A screenshot of a Mermaid flowchart using the Mermaid's dark theme.

A screenshot of a Mermaid flowchart using the Mermaid's forest theme.

A screenshot of a Mermaid flowchart using the Mermaid's neutral theme.

Mermaid 테마 커스터마이징

Quarto는 다이어그램 테마를 일부 조정할 수 있도록 Mermaid 전용 SCSS/CSS 변수를 제공합니다. 기본값과 함께 SCSS 변수는 다음과 같습니다.

$mermaid-bg-color: $body-bg;
$mermaid-edge-color: $secondary;
$mermaid-node-fg-color: $body-color;
$mermaid-fg-color: $body-color;
$mermaid-fg-color--lighter: lighten($body-color, 10%);
$mermaid-fg-color--lightest: lighten($body-color, 20%);
$mermaid-font-family: $font-family-sans-serif;
$mermaid-label-bg-color: $body-bg;
$mermaid-label-fg-color: $primary;
$mermaid-node-bg-color: rgba($primary, 0.1);
$mermaid-node-fg-color: $primary;

이에 대응하는 CSS 변수는 다음과 같습니다.

:root {
  --mermaid-bg-color: #{$mermaid-bg-color};
  --mermaid-edge-color: #{$mermaid-edge-color};
  --mermaid-node-fg-color: #{$mermaid-node-fg-color};
  --mermaid-fg-color: #{$mermaid-fg-color};
  --mermaid-fg-color--lighter: #{$mermaid-fg-color--lighter};
  --mermaid-fg-color--lightest: #{$mermaid-fg-color--lightest};
  --mermaid-font-family: #{$mermaid-font-family};
  --mermaid-label-bg-color: #{$mermaid-label-bg-color};
  --mermaid-label-fg-color: #{$mermaid-label-fg-color};
  --mermaid-node-bg-color: #{$mermaid-node-bg-color};
  --mermaid-node-fg-color: #{$mermaid-node-fg-color};
}

예를 들어 노드 배경색을 바꾸려면 다음 내용을 담은 사용자 정의 CSS 파일을 추가합니다.

:root {
  --mermaid-node-bg-color: #375a7f;
}

Quarto 변수와 Mermaid 기본 CSS 클래스 간 매핑은 Quarto 소스의 embed-mermaid.css에서 확인할 수 있습니다.

코드 표시

{python}과 같은 다른 실행 셀과 달리, 다이어그램 셀은 기본적으로 렌더링 결과에 코드가 나타나지 않습니다. 코드도 함께 보여 주고 싶다면 셀 맨 위 주석에 echo: true 옵션을 추가하세요.

{mermaid} 코드까지 표시하려면 셀 맨 위에 %%| echo: true를 추가합니다.

```{mermaid}
%%| echo: true
```

{dot} 코드도 표시하려면 셀 맨 위에 //| echo: true를 추가합니다.

```{dot}
//| echo: true
```

Chrome 설치

pdf, docx 같은 출력 형식으로 인쇄할 때는 Chrome 또는 Edge 브라우저를 사용해 고품질 PNG를 생성합니다.

Quarto는 시스템에 설치된 Chrome/Edge를 자동으로 사용하거나, 없다면 다음 명령으로 Quarto 전용 축소판 Chrome을 설치할 수 있습니다.

Terminal

quarto install chromium

Note

Quarto는 Puppeteer를 통해 헤드리스 Chromium을 설치합니다. Puppeteer가 설치하는 Chromium은 Docker 컨테이너에서 작동하지 않을 수 있으므로 Puppeteer 설명서와 이 문서를 참고해 주세요(특히 Windows Subsystem for Linux(WSL)에 설치할 때).