# 그림과 다이어그램

다이어그램 작성기: 캔버스에 그리거나 코드를 직접 작성합니다. LaTeX는 TikZ, Typst는 fletcher, Markdown은 Mermaid를 쓰며, 실시간 미리보기와 편집 가능한 소스를 제공합니다.

캔버스에 다이어그램을 그리면 문서 언어의 일반 소스 코드가 만들어집니다. LaTeX는 TikZ, Typst는 fletcher 다이어그램, Markdown은 Mermaid 순서도입니다. 그림과 코드는 항상 맞춰져 있으므로 언제든 둘 사이를 오갈 수 있습니다.

작성기는 여러분의 기기에서 실행되며 계정이 필요하지 않습니다. (어시스턴트가 작성하는 그림은 [AI로 그림 그리기](/docs/ai-figures/)를 참고하세요.)

## 작성기 열기

홈 화면에서 독의 **다이어그램 작성기**를 선택하세요. ⌘K(Ctrl+K) 명령 팔레트에서 **다이어그램 작성기 열기**를 실행하거나, 검색 옴니바에 `/diagram`을 입력해도 됩니다. **다이어그램 작성기 선택** 대화상자에서 다이어그램을 어디에 쓸지 묻습니다. LaTeX 문서에는 **TikZ 다이어그램**, Typst 문서에는 **Typst 다이어그램**, Markdown 문서에는 **Mermaid 다이어그램**을 고르세요.

열려 있는 문서에서는 편집기 도구 모음의 **다이어그램 그리기**를 선택하세요. 그러면 작성기가 질문을 건너뛰고 문서의 언어를 사용합니다. `.tex` 파일은 TikZ, `.typ` 파일은 Typst, Markdown 파일은 Mermaid입니다. **프로젝트로 돌아가기**를 누르면 문서로 돌아갑니다.

헤더에는 클릭해서 바꿀 수 있는 다이어그램 이름과, 언어를 나타내는 작은 레이블이 표시됩니다.

![코드로 작성한 TikZ 다이어그램을 캔버스에서 도형으로 편집하는 모습.](https://cdn.oleafly.com/images/gifs/desktop/tikz-composer.gif?v=2)

## 캔버스에 그리기

**그리기** 모드가 캔버스입니다. 세 언어 모두 같은 방식으로 동작합니다.

팔레트에서 도형(사각형, 둥근 상자, 원, 타원, 마름모, 평행사변형, 텍스트)을 고른 다음, 클릭한 채 끌어서 위치와 크기를 정하세요. **수식**과 **코드**는 다이어그램 언어의 수식이나 코드 예시로 시작하는 텍스트 상자입니다.

두 도형을 연결하려면 한 도형의 핸들에서 다른 도형으로 끌어 놓으세요. 어느 쪽 도형을 옮겨도 연결선은 붙은 채 유지됩니다. 연결선을 선택하면 화살촉(끝, 양쪽, 없음), 경로(직선, 직교, 곡선), 레이블을 고를 수 있습니다. 도형을 선택하면 레이블, 채우기, 테두리, 모서리 반경, 글꼴을 바꿀 수 있습니다.

도형은 움직일 때 정렬선에 맞춰 붙고, 실행 취소와 다시 실행은 평소처럼 동작합니다. Space를 누른 채 끌면 화면을 이동하고, 도형을 더블 클릭하면 텍스트를 편집합니다.

![fletcher 패키지로 그린 워크플로 다이어그램을 컴파일한 모습.](https://cdn.oleafly.com/images/gifs/desktop/typst-composer.gif?v=2)

## 코드 편집

**코드** 모드는 같은 다이어그램을 소스로 보여 주며, 사각형 노드, 원 노드, 화살표 간선, 선 간선 같은 자주 쓰는 조각을 담은 **스니펫** 메뉴가 있습니다. 어느 쪽을 편집해도 다른 쪽이 따라옵니다. 상자를 옮기면 코드가 바뀌고, 코드에서 레이블을 고치면 캔버스가 바뀝니다.

코드는 각 언어의 평범한 소스입니다.

- TikZ: 노드와 간선이 있는 `tikzpicture`.
- Typst: 완전한 fletcher 스니펫. `#import "@preview/fletcher:…"` 줄과, `node(…)`, `edge(…)` 항목을 담은 `#diagram(…)` 호출로 이루어집니다. fletcher 버전은 열려 있는 Typst 프로젝트의 Typst 버전에 맞춥니다. Typst 0.13 이상은 0.5.8, 0.12는 0.5.5, 그 이전 릴리스는 0.5.1입니다.
- Mermaid: 노드 도형, 레이블이 있는 링크, 색상을 위한 `style` 줄, 그룹 상자를 위한 서브그래프가 있는 순서도. Mermaid가 배치를 스스로 계산하므로 캔버스에서 정한 위치는 코드에 포함되지 않습니다.

### 캔버스가 그릴 수 없는 코드

Typst와 Mermaid에서는 캔버스가 보여 줄 수 없는 코드도 작성한 그대로 유지됩니다. Typst에서는 import, `#let` 줄, `#figure(…)` 같은 래퍼, 추가 다이어그램 설정, 반복문이 여기에 해당합니다. Mermaid에서는 `click` 줄, 지시문, 주석, 프런트매터가 해당합니다. 캔버스에서 건드리지 않은 노드나 간선은 텍스트가 그대로 유지되고, 건드린 것도 캔버스가 모르는 옵션은 그대로 유지됩니다.

캔버스에 모든 내용이 보이지 않을 때는 헤더에 **참고 사항 2개**처럼 개수가 적힌 노트 버튼이 나타납니다. 이 버튼은 코드에만 남아 있는 내용과, 크기가 정해지지 않은 노드, 서식이 있는 레이블, 캔버스에 없는 Mermaid 도형처럼 캔버스에 근사치로 표시되는 내용을 나열합니다.

TikZ는 다르게 동작합니다. 노트에는 캔버스가 모델링하지 않는 TikZ 명령이 나열되고, 캔버스를 편집하면 그림을 바탕으로 TikZ가 다시 작성되므로 그 명령은 사라집니다. 직접 작성한 TikZ나 복잡한 TikZ는 코드 모드에 두세요.

## 결과 미리보기

**컴파일**은 문서와 별개로 다이어그램만 렌더링하여 캔버스 옆 미리보기 창에 보여 줍니다. PNG 배율은 1x, 2x, 3x 중에서 고르고, 배경색이나 투명 배경도 고를 수 있습니다.

- TikZ는 별도의 빌드에서 Tectonic으로 컴파일하므로 미완성 다이어그램이 문서에 영향을 주지 않습니다.
- Typst는 열려 있는 Typst 프로젝트의 Typst 버전과 패키지 캐시로 미리 봅니다. 열려 있는 Typst 프로젝트가 없으면 번들된 Typst를 씁니다. 처음 Typst 미리보기를 할 때 Typst Universe에서 fletcher를 내려받습니다. 오프라인 모드이거나 연결이 없으면, 일반적인 오류 대신 패키지가 없다고 알려 줍니다.
- Mermaid는 앱에 내장된 Mermaid 렌더러로 미리 봅니다.

오류는 미리보기 창에 나타납니다. Typst와 Mermaid에서는 각 오류가 코드의 해당 줄을 알려 주며, 클릭하면 그 줄로 이동합니다.

컴파일이 실패하면 **AI로 수정**이 코드와 오류를 연결된 AI 제공자에 보내 같은 언어로 고친 코드를 요청합니다.

## 삽입, 저장, 다운로드

먼저 컴파일한 다음 **컴파일** 옆의 **저장** 메뉴를 엽니다.

- **TikZ로 삽입**, **Typst로 삽입**, **Mermaid로 삽입**은 열려 있는 `.tex`, `.typ`, Markdown 문서의 커서 위치에 그 문서의 언어로 다이어그램을 넣습니다. 작성기가 다른 언어로 설정되어 있으면 그림을 캔버스를 거쳐 변환하므로, 캔버스가 보여 줄 수 없는 코드는 넘어가지 않습니다.
- **프로젝트에 저장**은 목록에서 고른 프로젝트에 `figures/<name>.png`와 소스(`figures/<name>.tikz`, `.typ`, `.mmd`)를 씁니다. 다른 언어를 쓰는 프로젝트에 저장하면 그림을 그 프로젝트의 언어로 변환합니다. 이미 있는 파일을 바꾸기 전에는 Oleafly가 먼저 묻습니다. 저장한 Typst 다이어그램은 `#include`로 문서에 추가하고, Mermaid 다이어그램은 `mermaid` 코드 블록 안에 넣으세요.
- **프로젝트에 저장 → 새 프로젝트**는 작성기의 언어로 다이어그램 프로젝트를 만듭니다.
- **그림 저장**은 PNG와 그 소스를 프로젝트 밖에 있는 Oleafly의 그림 캐시에 보관합니다.

**다운로드** 메뉴는 PNG, Typst와 Mermaid 다이어그램의 SVG, 또는 **TikZ (.tikz)**, **Typst (.typ)**, **Mermaid (.mmd)** 소스를 저장합니다. 다른 언어로 다운로드하면 그림을 캔버스를 거쳐 변환합니다.

![Markdown 노트용으로 작성한 Mermaid 순서도를 미리 보는 모습.](https://cdn.oleafly.com/images/gifs/desktop/mermaid-composer.gif?v=2)

## Markdown 문서의 Mermaid

Markdown 문서에 삽입하면 `mermaid` 코드 블록이 추가되고, Markdown 미리보기가 이를 그려 줍니다. PDF에는 이미지가 필요하므로 작성기는 렌더링된 PNG도 `figures/mermaid-<hash>.png`에 저장하고, Markdown 컴파일은 블록 대신 그 이미지를 넣습니다. 그래서 다이어그램이 컴파일된 PDF에도 나타납니다. 나중에 블록을 직접 편집하면, 작성기에서 다이어그램을 다시 삽입하거나 저장하기 전까지 PDF에는 코드가 표시됩니다.

## 다이어그램 다시 열기와 가져오기

작성기가 저장하는 소스 파일은 끝에 캔버스 모델을 담은 한 줄 주석이 붙습니다. 그런 파일을 가져오면 그림이 떠날 때 모습 그대로 돌아옵니다.

헤더의 **다이어그램 파일 가져오기**는 `.tikz`, `.tex`, `.typ`, `.mmd`, `.md` 파일을 열어 현재 초안을 대체합니다. 다른 언어의 파일이면 작성기가 그 언어로 전환됩니다. 캔버스가 읽을 수 있는 코드는 그려지고, 나머지는 코드로만 열립니다.

## 다이어그램 프로젝트

다이어그램 프로젝트는 그림 하나를 담습니다. **프로젝트에 저장 → 새 프로젝트**로 세 언어 중 어느 것으로든 만들 수 있습니다. Typst 다이어그램 프로젝트에는 페이지 크기가 그림에 맞춰진 독립형 `main.typ`이 있어서, 컴파일하면 다이어그램 PDF가 나옵니다.

프로젝트의 메인 파일을 열고 편집기 도구 모음에서 **코드**를 **캔버스**(TikZ)나 **비주얼**(Typst와 Markdown)로 바꾸면 같은 캔버스에서 편집할 수 있습니다.

**Diagram / Figure** 템플릿(TikZ)과 **Typst Figure** 템플릿도 소스로 작성된 그림 하나짜리 프로젝트를 시작합니다. 이런 프로젝트는 그림 자체로 미리 보이고, [내보내기 메뉴](/docs/export/)에는 **PDF로 내보내기(벡터 이미지)** 항목과 **PNG로 내보내기** 항목이 나옵니다. 여러 논문에서 재사용하는 그림에 쓰세요.
