# Typst로 쓰기

Typst 논문, 보고서, 이력서를 코드 또는 비주얼 모드로 쓰고, Typst를 대신 써 주는 툴바를 활용합니다.

Typst 템플릿을 고르고 컴파일된 PDF 옆에서 `.typ` 소스를 편집하세요. 툴바가 Typst 문법을 대신 써 주므로 모든 변경이 소스에 남고, 언제든 읽고 편집할 수 있습니다. 마크업을 보고 싶지 않을 때는 파일을 비주얼 모드로 전환하세요.

![서식 툴바, 소스, 컴파일된 보고서가 보이는 Typst 예제.](https://cdn.oleafly.com/images/screenshots/desktop/docs/typst-writing-dark-window-v2.png)

## 간단한 보고서 컴파일하기

1. **새 프로젝트 → 템플릿 사용 → Blank Typst document**를 선택합니다.
2. 이름을 **측정 메모**로 정하고 `main.typ`을 엽니다.
3. 아래 예제를 붙여 넣은 다음 **다시 컴파일**을 선택하거나 **⌘Enter / Ctrl+Enter** 를 누릅니다.

```typst title="main.typ"
#set document(title: "Measurement note", author: "Alex Chen")
#set page(paper: "a4", margin: 25mm)
#set heading(numbering: "1.")

= Measurement note
A short report on repeated measurements.

== Method <method>
We collect three observations and compare their mean.

$ overline(x) = (1 + 2 + 3) / 3 = 2 $

== Results
See @method for the procedure.

#table(
  columns: 2,
  [Run], [Value],
  [1], [1],
  [2], [2],
  [3], [3],
)
```

PDF에 번호가 붙은 제목, 별행 수식, 방법 절에 대한 참조, 두 열짜리 표가 보여야 합니다.

입력하는 대로 PDF가 바뀌는 것을 보려면 **다시 컴파일** 옆의 화살표를 열고 **자동 컴파일**을 **켜기**로 설정하세요. Typst 프로젝트에서는 그것이 실시간 미리 보기입니다. [자동 컴파일로 실시간 미리 보기](/docs/typst/#live-preview-with-auto-compile)를 참고하세요.

[예제 소스 내려받기](/examples/writing-example.typ)

## 모든 툴바 도구

서식 도구를 쓰기 전에 텍스트를 선택하면 그 텍스트를 감쌉니다. 선택한 것이 없으면 툴바가 덮어 쓸 수 있는 자리 표시자를 넣습니다. 편집기가 좁아 모든 버튼이 들어가지 않으면, 넘치는 버튼은 **서식 옵션 더 보기**(`…`)로 들어갑니다. 대부분의 도구는 편집기의 오른쪽 클릭 메뉴에도 있습니다.

### 코드 / 비주얼

툴바 맨 앞의 스위치는 파일을 보여 주는 방식을 바꿉니다. **코드**는 Typst 소스를 보여 줍니다. **비주얼**은 제목, 강조, 목록, 수식, 이미지, 표, 참조, 각주를 제자리에 그리고, 커서가 있는 줄에서는 소스를 다시 보여 줍니다. 두 모드에서 파일은 같습니다. 자세한 내용은 [Typst의 비주얼 모드](#visual-mode)에 있습니다.

### 실행 취소

마지막 편집을 되돌립니다. ⌘Z / Ctrl+Z. 되돌릴 것이 없으면 버튼이 흐리게 표시됩니다.

### 다시 실행

되돌린 편집을 다시 적용합니다. **⌘Shift+Z / Ctrl+Shift+Z**.

### 제목 → 제목

제목을 선택하고 **제목**을 고릅니다. `= Title`.

### 제목 → 절

문서 안에 절을 추가합니다. `== Section`.

### 제목 → 소절

절 아래 수준을 추가합니다. `=== Subsection`.

### 제목 → 소소절

네 번째 수준의 제목을 추가합니다. `==== Subsubsection`.

### 제목 → 작은 제목

다섯 번째 수준의 제목을 추가합니다. `===== Minor heading`.

### 제목 → 단락 제목

여섯 번째 수준의 제목을 추가합니다. `====== Paragraph heading`.

### 굵게

"three observations"를 선택합니다. `*three observations*`; ⌘B / Ctrl+B.

### 기울임

강조할 용어를 선택합니다. `_term_`; ⌘I / Ctrl+I.

### 밑줄

구절을 선택합니다. `#underline[phrase]`.

### 취소선

더 이상 쓰지 않는 구절을 표시합니다. `#strike[phrase]`.

### 인라인 코드

파일 이름이나 변수 이름을 선택합니다. 백틱으로 감쌉니다.

### 링크 삽입

`url`, 그다음 `text`를 바꿉니다. `#link("url")[text]`.

### 프로젝트에서 인용

키, 저자, 제목으로 프로젝트의 참고문헌을 검색하고 항목을 고릅니다. Oleafly가 `@key`를 씁니다. 문서에 아직 `#bibliography` 호출이 없으면 Oleafly가 하나를 추가합니다. 목록 맨 아래의 **새 인용 찾아서 추가…** 는 새 자료를 찾는 검색을 엽니다. [인용 추가하기](#add-citations)를 참고하세요.

### 상호 참조 삽입

프로젝트의 레이블 목록에서 하나를 골라 `@label`을 씁니다. 예제에서는 `method`를 골라 `@method`를 얻습니다. **여기에 레이블 추가**는 대신 커서 위치의 항목에 새 레이블을 붙입니다.

### 레이블 추가

제목, 그림, 수식 안에 커서를 두고 **레이블 추가**를 선택합니다. 예제의 Results 제목에서는 Oleafly가 `<sec:results>`를 추가합니다. 항목에 이미 레이블이 있으면 버튼이 그 레이블을 선택합니다.

### 각주 삽입

단어 뒤에 커서를 둡니다. `#footnote[note text]`.

### 인용 블록 삽입

새 줄에 커서를 둡니다. `#quote(block: true)[quote]`.

### 그림 삽입

그림 대화 상자를 엽니다. **프로젝트 이미지**에서 이미지를 고르거나 **디스크에서 가져오기…** 를 선택한 다음, 너비, 캡션, 레이블, 대체 텍스트, 배치를 정합니다. 기존 `#figure` 안에 커서가 있으면 같은 버튼이 **그림 편집**을 열어 이 값들을 바꿀 수 있습니다. [캡션이 있는 그림 추가하기](#add-a-captioned-figure)를 참고하세요.

### 표 삽입

격자를 열고 행과 열의 수를 고릅니다. Oleafly는 머리글 행과 위, 가운데, 아래 괘선이 있는 `table`을 담은 `#figure`를 넣고, `caption: [Caption]`과 레이블 `<tab:label>`도 함께 넣습니다. 캡션, 레이블, 빈 셀을 바꾸세요. 대신 스프레드시트로 표를 만들려면 [데이터 파일로 표 만들기](#tables-from-data-files)를 참고하세요.

### 이미지 삽입

이미지를 가져온 다음 선택된 파일 이름을 상대 경로로 바꿉니다. `#image("image-filename")`. 이미지 파일을 편집기에 붙여 넣거나 끌어다 놓아도 되며, 그러면 Oleafly가 프로젝트에 저장하고 그 이미지를 쓰는 그림을 넣습니다.

### 다이어그램 그리기

[다이어그램 구성기](/docs/figures-diagrams/)를 Typst 모드로 엽니다. 캔버스에 그리거나 fletcher 코드를 편집한 다음 **Typst로 삽입**을 선택하면 다이어그램이 커서 위치에 들어갑니다. 첫 미리 보기에서 Typst Universe의 fletcher 패키지를 내려받으므로 온라인 상태여야 합니다.

### 이미지를 Typst로

수식이나 텍스트의 스크린샷을 고르면 커서 위치에 Typst로 옮겨 적습니다. 도구에 쓸 모델(다른 모델을 고르지 않으면 로컬 Ollama 모델)을 사용합니다. 모델을 고르지 않았고 Ollama가 실행 중이 아니거나 이미지를 읽는 모델이 없다면 대신 어시스턴트의 모델을 사용하며, 이때 이미지는 그 제공자로 전송됩니다. 결과를 확인하고 컴파일하세요.

### 목록 → 글머리 기호 목록

관찰 목록을 시작합니다. `- Item`.

### 목록 → 번호 목록

단계 순서를 시작합니다. `+ Item`.

### 수식

`x`를 선택하고 수식 아이콘을 클릭합니다. `$x$`.

### 별행 수식

한 줄을 따로 차지하는 수식입니다. `$ x $`처럼 각 `$` 안쪽에 공백을 둡니다.

### 번호 붙은 수식

`$ x $ <eq:label>`처럼 레이블이 있는 별행 수식입니다. Typst는 문서에 번호 규칙이 있을 때만 수식에 번호를 붙입니다. 규칙이 없으면 안내 문구가 **규칙 추가**를 제안하며, 이는 파일 맨 위 근처에 `#set math.equation(numbering: "(1)")`을 추가합니다.

### 정렬된 수식

여러 수식을 `&`에 맞춰 정렬하고 행 사이에 `\`를 둡니다. `$ a &= b \ c &= d $`.

### 분수

`frac(a, b)`를 넣으며, 커서가 아직 수식 안에 있지 않으면 `$`로 감쌉니다. 텍스트를 선택한 상태라면 선택한 부분이 분자가 됩니다.

### 기호

기호 선택기를 열고 기호를 검색해 선택합니다. Oleafly는 Typst 이름으로 씁니다. 수식 안에서는 `arrow.r`, 본문에서는 `#sym.arrow.r`입니다.

### 코드 블록

여러 줄의 코드를 선택하거나 자리 표시자를 바꿉니다. 세 개의 백틱으로 감싼 블록입니다. 강조 표시를 하려면 여는 펜스 뒤에 언어를 적으세요.

### 코드 인텔리전스 → 정의로 이동

레이블, 변수, 함수 위에 커서를 두고 이 동작을 고르거나 F12를 누릅니다. 다른 파일에 있어도 정의된 곳을 엽니다.

### 코드 인텔리전스 → 참조 찾기

레이블, 변수, 함수가 쓰인 모든 곳을 나열합니다. ⇧F12.

### 코드 인텔리전스 → 심볼 이름 바꾸기

프로젝트 전체에서 레이블, 변수, 함수의 이름을 바꿉니다. F2. 세 가지 모두 [코드 인텔리전스](/docs/code-intelligence/#typst-files)에서 다룹니다.

### Typst 패키지

막대 오른쪽 끝의 패키지 아이콘은 Typst Universe를 검색하고 `#import` 줄을 넣습니다. 자세한 내용은 [패키지, 설정, 분석](#packages-settings-and-insights)에 있습니다.

### 문서 분석

문서의 제목, 그림, 표, 수식, 레이블, 인용, 할 일을 각각의 줄로 연결해 나열합니다. [문서 분석](/docs/document-insights/)을 참고하세요.

### 문서 설정

문서의 `#set` 규칙을 편집해 쪽 크기, 여백, 글꼴, 언어, 양쪽 정렬, 줄 간격, 번호 매기기를 바꿉니다. [문서 설정](/docs/document-settings/)을 참고하세요.

### 프로젝트 정보

문서와 선택한 부분의 단어, 그림, 수식 개수와 교정 결과를 보여 줍니다.

### 찾기

현재 파일에서 단어를 검색합니다. ⌘F / Ctrl+F.

### PDF로 이동

커서 위치에서 컴파일된 PDF의 해당 위치로 이동합니다. 이 버튼은 Typst 0.13 이상에서 나타납니다. [소스와 PDF 사이 이동하기](#jump-between-the-source-and-the-pdf)를 참고하세요.

## 비주얼 모드

아무 `.typ` 파일에서나 툴바를 **코드**에서 **비주얼**로 전환하세요. 비주얼 모드는 마크업을 제자리에 그려 주는 같은 편집기입니다.

- 제목, 강한 강조와 강조 텍스트, raw 텍스트, 링크, 색 텍스트
- 기호가 붙은 글머리 기호 목록, 번호 목록, 용어 목록
- Typst가 그리는 인라인 수식과 별행 수식
- 캡션이 텍스트로 표시되는 이미지와 그림
- 바로 입력할 수 있는 격자 형태의 표. 셀을 선택하면 테두리, 정렬, 행, 열을 다루는 작은 툴바가 나타납니다.
- 칩으로 표시되는 참조와 인용, 작은 표식으로 표시되는 각주

줄에 커서를 두면 그 줄의 소스가 다시 나타나 편집할 수 있습니다. 커서를 옮기면 렌더링된 형태로 돌아옵니다. 파일 맨 위의 `#set`, `#show`, `#import`, `#let` 줄은 **문서 설정 보기** 막대로 접히며, 클릭하면 펼쳐집니다. 비주얼 모드가 그릴 수 없는 것은 소스 그대로 화면에 남습니다. 모든 툴바 버튼은 두 모드에서 같은 Typst를 쓰며, 줄 번호, 찾기, 맞춤법, 컴파일 오류도 계속 동작합니다.

새 프로젝트는 코드 모드로 열리고, 각 프로젝트는 마지막으로 둔 모드를 기억합니다. 세 언어 모두의 전환 방법은 [비주얼 편집](/docs/editor/#visual-editing)에서 다룹니다.

## 입력하는 동안 받는 도움

Typst 파일은 LaTeX 파일과 같은 도우미를 Typst 문법에 맞춰 받습니다.

- 여백의 화살표를 클릭하면 제목을 같은 수준의 다음 제목까지 접습니다. 코드 블록, 콘텐츠 블록, 수식, 긴 인수 목록도 접힙니다. [코드 접기](/docs/editor/#code-folding)를 참고하세요.
- 스크롤하면 커서 위의 제목이 편집기 맨 위에 고정됩니다. 파일 위의 이동 경로 막대가 지금 있는 절을 알려 주며, 항목을 클릭하면 그 제목으로 이동합니다.
- `$`를 입력하면 닫는 `$`가 추가되고, 빈 쌍 안에 공백을 넣으면 별행 수식이 됩니다. 목록 항목에서 Enter를 누르면 다음 항목이 시작됩니다. 나머지는 [Typst 입력 도우미](/docs/editor/#typst-typing-aids)에 나와 있습니다.
- Typst 언어 서버가 함수, 파일 경로, 레이블, 인용 키, 패키지, 참고문헌 스타일을 자동 완성합니다. [Typst 자동 완성](/docs/autocomplete/#typst-completion)을 참고하세요.
- 줄 맨 앞이나 공백 뒤에서 `/`를 입력하면 스니펫이 나옵니다. 제목, 그림, 표, 수식, 각주, 개요, 참고문헌 등입니다.
- ⌘/ / Ctrl+/는 선택한 줄을 `//`로 주석 처리하거나 해제합니다.

### 수식 미리 보기

수식 안에 커서가 있으면 Typst가 결과를 바로 위에 그립니다. 미리 보기 메뉴에서 수식을 벗어날 때까지 숨기거나 끌 수 있습니다.

`$\frac{a}{b}$` 같은 LaTeX 수식을 Typst 파일에 붙여 넣으면 그 아래에 **Typst 수식으로 붙여넣기** 버튼이 나타납니다. 클릭하면 붙여 넣은 내용을 Typst 수식으로 바꾸고, Esc를 누르면 LaTeX를 그대로 둡니다. 파일에 이미 있는 LaTeX 수식은 선택한 뒤 오른쪽 클릭 메뉴에서 **LaTeX 수식을 Typst로 변환**을 고르세요. 한 번만 변환할 때는 [수식을 Typst로](/docs/tools/equation-to-typst/) 도구가 프로젝트 밖에서 같은 일을 합니다.

## 캡션이 있는 그림 추가하기

1. 툴바에서 **그림 삽입**을 선택합니다.
2. **프로젝트 이미지**에서 `plot.png`를 고르거나 **디스크에서 가져오기…** 로 프로젝트에 복사합니다.
3. **4분의 3 너비**를 고른 다음 **캡션 추가**와 **레이블 추가**를 켭니다. 캡션과 레이블 `fig:measurements`를 입력합니다.
4. 화면 낭독기를 위해 이미지를 설명하는 **대체 텍스트**를 추가하고, 그림이 쪽의 위나 아래로 떠야 한다면 **배치**를 고릅니다.
5. **그림 삽입**을 선택합니다.

Oleafly는 이런 그림을 씁니다.

```typst
#figure(
  image("figures/plot.png", width: 75%),
  caption: [Measurements across three runs.],
) <fig:measurements>

See @fig:measurements for the comparison.
```

나중에 그림을 바꾸려면 그림 안에 커서를 두고 다시 **그림 삽입**을 선택하세요. 대화 상자가 현재 값과 함께 **그림 편집**으로 열립니다.

## 데이터 파일로 표 만들기

편집기에서 오른쪽 클릭을 하고 **CSV/XLSX로 표 만들기…** 를 고릅니다. CSV, TSV, Excel, JSON 파일을 고르고 미리 보기를 확인한 뒤, 원하면 캡션과 레이블을 추가합니다. **커서 위치에 삽입**은 툴바의 표와 같은 괘선을 가진 Typst 표를 씁니다. Typst가 마크업으로 읽을 셀 텍스트는 이스케이프됩니다.

**데이터 파일과 연결 유지**를 켜면 표가 데이터에 계속 묶입니다. Oleafly는 데이터를 프로젝트의 `data` 폴더로 복사하고, 표는 문서를 컴파일할 때마다 그 파일을 읽습니다. 파일을 편집하면 다음 컴파일에서 표가 바뀝니다. 대화 상자 전체는 [데이터 파일에서 표 가져오기](/docs/writing/tables-equations/#import-a-table-from-a-data-file)에서 다룹니다.

## 인용 추가하기

**프로젝트에서 인용**으로 인용하거나, `@`를 입력하고 자동 완성 목록에서 키를 고르세요. Typst에서는 인용 키와 문서 레이블이 모두 `@`를 쓰며, 참고문헌이나 레이블이 대상을 정합니다.

참고문헌 목록이 나타날 곳에 참고문헌을 두세요.

```typst
#bibliography("references.bib")
```

파일은 BibTeX(`.bib`)나 Hayagriva(`.yml`)일 수 있고, 호출에 파일 목록을 줄 수도 있습니다. [참고문헌과 인용](/docs/citations/)에서 추가한 인용은 문서가 선언한 파일로 들어가며, 그 파일에 필요하면 Hayagriva로 변환됩니다. 참고문헌 스타일을 바꾸려면 참고문헌 패널 아래쪽의 **인용 스타일** 메뉴를 쓰세요. `style:` 인수를 대신 써 줍니다. [Typst 인용 스타일 고르기](/docs/citations/#choose-a-typst-citation-style)를 참고하세요.

## 패키지, 설정, 분석

툴바 오른쪽 끝의 세 버튼은 문서 전체에 작용합니다.

- **Typst 패키지**는 Typst Universe를 검색하고 `#import` 줄을 씁니다. import가 오래된 릴리스를 가리키면 편집기가 업데이트를 제안합니다. 프로젝트가 패키지 사본을 직접 보관해 오프라인에서도 컴파일되게 할 수도 있습니다. [패키지](/docs/packages/#typst-packages)와 [Typst Universe의 패키지](/docs/typst/#packages-from-typst-universe)를 참고하세요.
- **문서 분석**은 제목, 그림, 표, 수식, 레이블, 인용, 할 일을 나열하고, 제출 양식에 쓸 제목, 저자, 키워드, 초록을 복사합니다. 대화 상자를 열 때 Typst가 문서를 읽으므로 번호와 쪽이 최신입니다. [문서 분석](/docs/document-insights/)을 참고하세요.
- **문서 설정**은 쪽 크기, 여백, 단, 본문 글꼴, 크기, 언어, 양쪽 정렬, 줄 간격, 제목과 수식 번호 매기기를 바꿉니다. Oleafly는 선택한 내용을 주 파일의 `#set` 규칙에 씁니다. 프로젝트의 빌드 변형도 여기에 있습니다. [문서 설정](/docs/document-settings/)을 참고하세요.

## 오류와 점검

컴파일이 실패하면 각 오류가 해당 파일에서 Typst가 보고한 정확한 범위에 밑줄로 표시됩니다. 밑줄 위에 포인터를 올리면 메시지와 Typst의 힌트를 읽을 수 있습니다. 알 수 없는 이름, 없는 파일이나 패키지, 닫히지 않은 괄호 같은 흔한 오류에는 쉬운 설명이 붙습니다. [소스의 컴파일 오류](/docs/editor/#compile-errors-in-the-source)를 참고하세요.

[맞춤법과 문법](/docs/spellcheck-grammar/) 검사는 캡션, 표 셀, `abstract:` 같은 템플릿 필드를 포함해 Typst 파일의 글을 검사하고 코드는 건너뜁니다. [프리플라이트](/docs/preflight/#typst-projects)는 Typst 소스에서 해결되지 않은 참조와 인용, 빠진 대체 텍스트, 없는 이미지, 문서 메타데이터, 익명 심사 문제를 점검합니다.

## 소스와 PDF 사이 이동하기

툴바에서 **PDF로 이동**을 선택하거나 ⌘⇧J / Ctrl+Shift+J를 누르면 커서 위치에서 해당 쪽으로 이동합니다. PDF에서 ⌘ 또는 Ctrl을 누른 채 단어를 클릭하면 그 줄로 돌아가며, `#include`로 불러온 파일이어도 됩니다. 동기화에는 Typst 0.13 이상이 필요합니다. [소스와 PDF 동기화](/docs/synctex/#typst-projects)를 참고하세요.

## 파일 서식 정리하기

**문서 서식 지정**은 typstyle로 파일 전체를 정리합니다. ⇧⌥F / Shift+Alt+F를 누르거나 오른쪽 클릭 메뉴에서 고르세요. **선택 영역 서식 지정**은 선택한 줄만 정리합니다. ⌘S / Ctrl+S를 누를 때마다 서식을 정리하려면 **설정 → 모양 → 편집기**의 **Typst** 아래에서 **저장할 때 서식 지정**을 켜세요. [Typst 파일 서식 지정](/docs/code-intelligence/#format-a-typst-file)을 참고하세요.

## Typst 버전

Oleafly에는 Typst 0.15.1이 들어 있고, **설정 → 엔진 → Typst**에서 내려받을 수 있는 Typst 0.11부터 0.15까지가 나열됩니다. 새 프로젝트는 기본 버전으로 고정되므로, 나중에 Oleafly가 더 새로운 Typst를 내놓아도 줄바꿈과 쪽수가 그대로 유지됩니다. 한 프로젝트의 버전을 바꾸려면 **다시 컴파일** 옆의 화살표를 열고 **Typst 버전(이 프로젝트)** 아래에서 고르세요. 언어 서버는 프로젝트의 버전을 따라갑니다. 고정, 없는 버전, 바꾸기 전에 새 릴리스를 시험하는 방법은 [Typst 버전](/docs/typst/#typst-versions)에서 설명합니다.

## 정리하고 내보내기

긴 보고서는 여러 파일로 나누고 `#include "sections/method.typ"`로 불러오세요. 그림, 데이터, 글꼴, 참고문헌 파일을 프로젝트 안에 두면 소스 ZIP에 문서에 필요한 모든 것이 함께 담깁니다.

컴파일해서 결과를 확인한 다음 **내보내기**를 엽니다. **PDF로 내보내기**, **소스 내보내기(.zip)**, **쪽을 PNG로 내보내기**, 그리고 Typst로 PNG나 SVG 쪽 또는 HTML 파일을 쓰는 **이미지와 HTML**이 있습니다. Typst 0.13 이상에서는 Word, HTML, Markdown, LaTeX, 일반 텍스트 내보내기가 Typst 자체의 HTML 출력을 거치므로 수식과 참조가 그대로 남습니다. [프로젝트 내보내기와 변환](/docs/export/#typst-images-and-html)을 참고하세요. 로그와 컴파일 옵션은 [컴파일](/docs/compiling/)에서, 프로젝트 구성은 [파일과 폴더](/docs/files/)에서 다룹니다.

기존 LaTeX 프로젝트를 Typst로 옮기려면 [LaTeX 프로젝트를 Typst로 변환하기](/docs/typst/#convert-a-latex-project-to-typst)를 참고하세요.