# 문서 엔진 선택하기

LaTeX, Typst, Markdown, Quarto, Calepin 문서가 PDF가 되는 과정을 이해하고, 프로젝트에 맞는 컴파일러를 고르세요.

엔진은 소스를 사람들이 읽는 문서로 바꿔 줍니다. 프로젝트를 만들 때 문서 언어를 고르세요. LaTeX 프로젝트에서는 빌드를 실행할 LaTeX 컴파일러도 고를 수 있습니다.

## 언어 고르기

| 작업 | 시작점 | PDF가 되는 방식 |
|---|---|---|
| 학술지 투고, 기존 학위논문 클래스, 이미 있는 `.tex` 프로젝트 | LaTeX | Tectonic, 또는 `latexmk`로 실행하는 컴파일러 |
| 간결한 조판 문법으로 쓰는 새 논문, 보고서, 이력서 | Typst | 내장 Typst 0.15.1, 또는 프로젝트가 고정한 다른 Typst 버전 |
| 글 초안, 메모, 여러 형식으로 내보내고 싶은 문서 | Markdown | Pandoc이 소스를 LaTeX로 변환하고, Tectonic이 PDF를 만듭니다 |
| R, Python, Julia 코드가 결과를 만들어 내는 분석 보고서, 논문, 슬라이드 | Quarto | Quarto가 `.qmd`나 `.Rmd` 파일을 PDF, 웹 페이지, 슬라이드로 렌더링합니다 |
| 코드 청크가 있는 Typst 문서 | Calepin | Calepin이 코드를 실행한 다음, 내장 Typst가 PDF를 빌드합니다 |

이 선택에 따라 편집기 도구 모음, 소스 문법, 사용할 수 있는 내보내기 형식이 정해집니다. LaTeX 컴파일러를 바꾼다고 문서가 Typst나 Markdown으로 변환되지는 않습니다. LaTeX 프로젝트를 Typst로 옮기려면 [새 Typst 프로젝트로 변환](/docs/typst/#convert-a-latex-project-to-typst)하세요.

## Tectonic

간단한 LaTeX 환경에는 **Tectonic**을 사용하세요. Oleafly에 포함되어 있으며, 빌드에 필요한 TeX 패키지를 내려받아 이후 빌드를 위해 캐시합니다. 템플릿이 특정 컴파일러를 요구하지 않는다면 여기서 시작하세요.

이동하기 전에 온라인 상태에서 한 번 컴파일해 두세요. 캐시된 프로젝트는 오프라인에서도 컴파일할 수 있지만, 새 패키지는 다운로드가 필요할 수 있습니다. **설정 → 일반 → 오프라인 모드**를 켜면 Tectonic이 캐시를 사용합니다.

## pdfLaTeX

출판사나 기존 프로젝트가 지정했다면 **pdfLaTeX**을 선택하세요. 전통적인 LaTeX 작업 흐름을 따르며, 오래된 클래스와 패키지 조합에 잘 맞습니다. `latexmk`가 설치된 TeX 배포판이 필요합니다.

## XeLaTeX

프로젝트가 요구한다면 **XeLaTeX**을 선택하세요. 특히 `fontspec`, OpenType 글꼴, 다국어 텍스트를 쓰는 프로젝트에 적합합니다. 소스에 지정된 글꼴이 설치되어 있거나 프로젝트에 포함되어 있는지 확인하세요. 이것도 `latexmk`를 통해 실행됩니다.

## LuaLaTeX

템플릿이 요구하거나, Lua 기반 조판을 쓰거나, Oleafly의 태그된 PDF 작업 흐름을 쓸 때 **LuaLaTeX**을 선택하세요. 태그된 PDF에는 보조 기술이 활용할 수 있는 문서 구조가 담겨 있습니다. 결과는 [프리플라이트 검사](/docs/preflight/)로 확인하세요. 컴파일러를 고르는 것만으로 태그의 품질이 보장되지는 않습니다.

## Typst

Oleafly에는 Typst 0.15.1이 들어 있습니다. Typst 프로젝트를 만들고 `.typ` 파일에 작성한 다음 **다시 컴파일**을 클릭하세요. 따로 설정할 TeX 설치는 없습니다.

**설정 → 엔진 → Typst**에서 Typst 0.11부터 0.15까지 설치하거나, 컴퓨터에 이미 설치된 Typst를 사용할 수도 있습니다. 프로젝트마다 자기 버전을 고정하므로, Oleafly가 더 새로운 Typst로 옮겨 가도 논문의 레이아웃은 그대로입니다. Typst는 문서가 패키지를 처음 가져올 때 Typst Universe에서 내려받으며, **오프라인 모드**를 켜면 이미 캐시되었거나 프로젝트에 들어 있는 패키지로 제한됩니다.

Typst에는 고유한 문법, 패키지, 글꼴 처리 방식이 있습니다. [Typst 프로젝트](/docs/typst/)는 버전, 패키지, 글꼴, 빌드 변형을 다룹니다. [Typst 작성 가이드](/docs/writing/typst/)에는 완전한 시작 문서와 도구 모음 컨트롤이 있습니다.

## Markdown

Markdown은 **Pandoc**으로 조판된 문서를 준비하고 Tectonic으로 PDF를 빌드합니다. Pandoc이 없다면 **설정 → 엔진 → Markdown**을 열어 설치하세요. 그런 다음 Markdown 프로젝트를 열고 컴파일합니다.

제목, 목록, 수식, 비주얼 편집기는 [Markdown 작성](/docs/writing/markdown/)을 참고하세요. 프로젝트에서 제공하는 출력 형식은 [내보내기 가이드](/docs/export/)에서 설명합니다.

## Quarto

Quarto는 `.qmd`와 `.Rmd` 문서를 PDF, 웹 페이지, 슬라이드로 바꿉니다. 컴퓨터에 Quarto가 있으면 Oleafly가 그것을 씁니다. 없다면 **설정 → 엔진 → Quarto**를 열고 **Quarto 1.10.19 내려받기**를 선택하세요. 버튼에는 다운로드 크기도 표시됩니다. Oleafly는 압축을 풀기 전에 다운로드를 확인하고, 사본을 자체 앱 폴더에 보관합니다. Quarto가 준비되기 전에 컴파일하면 미리보기에서 바로 설치하거나 **엔진 설정 열기**를 고를 수 있습니다.

문서가 선언한 첫 번째 형식에 따라 결과물이 정해집니다.

- `pdf`, `typst`, `beamer`는 PDF를 빌드합니다. `format: typst`에는 TeX 설치가 필요 없습니다. `pdf`와 `beamer`는 LaTeX를 거치므로, 아직 TeX가 없다면 **설정 → 엔진 → LaTeX**에서 TinyTeX를 설치하세요.
- `html`, `revealjs`, `dashboard`는 웹 페이지를 빌드합니다. 결과를 보려면 미리보기에서 **브라우저에서 열기**를 선택하세요.

문서가 형식을 선언하지 않으면 Oleafly는 문서가 있는 폴더부터 프로젝트 루트까지 위쪽 폴더에서 `_quarto.yml`이나 `_metadata.yml`을 찾아 형식을 읽습니다. 어디에도 형식이 없으면 Quarto는 웹 페이지를 빌드합니다. `pdf_document`처럼 R Markdown `output:`을 지정한 `.Rmd` 파일은 그에 맞는 Quarto 형식을 씁니다.

코드는 컴퓨터에 이미 있는 R, Python, Julia에서 실행됩니다. Oleafly는 이 언어들을 설치하지 않으며, 같은 설정 탭의 **언어**에 찾아낸 언어가 표시됩니다. Python 코드를 실행하려면 그 Python에 Jupyter도 있어야 합니다. 내보내기는 DOCX와 HTML을 제공하며, 둘 다 Quarto가 렌더링합니다. **새 프로젝트** 대화상자에는 Quarto 템플릿이 두 개 있습니다. Typst를 거쳐 PDF로 빌드되는 **Quarto article**과 reveal.js 슬라이드인 **Quarto slides**입니다.

## Calepin

Calepin은 Typst 문서 안의 코드를 실행하고 그 결과를 PDF에 넣습니다. Calepin 문서는 `/.calepin/calepin.typ`를 가져오는 `.typ` 파일입니다. **Calepin report** 템플릿으로 시작하거나, Typst 프로젝트에서 **다시 컴파일** 옆의 화살표를 열고 **엔진(이 프로젝트)** 아래에서 **Calepin**을 고르세요.

Quarto와 같은 방법으로 **설정 → 엔진 → Calepin**에서 **Calepin 0.0.61 내려받기**를 선택해 설치하세요. Calepin은 Oleafly에 들어 있는 Typst로 빌드합니다. 언어가 설치되지 않은 청크에는 짧은 메모가 표시되고, 문서의 나머지는 그대로 빌드됩니다. 내보내기는 Calepin이 렌더링하는 HTML을 제공합니다.

## 프로젝트에서 코드 허용하기

Quarto나 Calepin 문서의 코드는 내 권한으로 실행되므로, 허용하기 전까지 프로젝트마다 꺼져 있습니다. 코드가 필요한 컴파일을 하고 나면 편집기 위의 배너가 코드가 꺼져 있다고 알리고 **이 프로젝트에서 코드 허용**을 제안합니다. **다시 컴파일** 옆의 화살표를 열고 **코드(이 컴퓨터)** 아래에서 **이 컴퓨터에서 코드 실행**을 골라도 됩니다. **끄기**를 고르면 다시 꺼집니다. 프로젝트의 모든 파일을 신뢰할 때만 코드를 허용하세요.

이 선택은 이 컴퓨터에만 적용됩니다. 프로젝트에 저장되지 않으며, 프로젝트의 엔진을 바꾸면 코드가 다시 꺼집니다. [공유 프로젝트](/docs/collaboration/)에서는 프로젝트를 편집할 수 있는 사람이면 누구나 코드를 바꿀 수 있으므로 Oleafly가 한 번 더 묻습니다.

코드가 꺼져 있는 동안에는 다음과 같습니다.

- Quarto는 각 청크의 코드를 실행하지 않고 보여 줍니다. 필터, 단축 코드, `_extensions`, 렌더링 전후 스크립트, 인라인 R 코드는 이때도 코드를 실행하므로, 이런 기능을 쓰는 문서는 코드를 허용할 때까지 컴파일되지 않습니다.
- Calepin은 코드를 건너뛸 수 없습니다. Oleafly는 Calepin이 마지막으로 실행될 때 저장한 결과로 일반 Typst를 써서 PDF를 빌드합니다. 저장된 결과가 없으면 컴파일이 멈추고 코드를 허용하라고 요청합니다.

[제자리에서 연](/docs/library/#folders-opened-in-place) 폴더도 신뢰해야 Quarto나 Calepin이 컴파일할 수 있습니다. 두 엔진 모두 소스와 PDF 동기화를 지원하지 않습니다.

## 새 프로젝트의 기본값 설정

**설정 → 엔진 → LaTeX**을 열고 **기본 컴파일 엔진**에서 **Tectonic(내장)** 또는 **latexmk(시스템 TeX)** 중 하나를 선택하세요. 이후 만드는 모든 LaTeX 프로젝트가 이 엔진으로 시작합니다.

- **새 프로젝트** 대화상자의 빈 프로젝트나 템플릿, 그리고 연구 프로젝트.
- 가져온 ZIP, 폴더, arXiv 논문, GitHub 저장소.
- Word 파일이나 PDF처럼 LaTeX 프로젝트로 변환한 문서.

엔진은 프로젝트의 `project.json`에 기록되므로, 프로젝트를 여는 공저자도 같은 방식으로 컴파일합니다. pdfLaTeX, XeLaTeX, LuaLaTeX 중 하나를 지정한 채 가져온 프로젝트는 `latexmk`로 옮겨져도 그 컴파일러를 유지합니다. 기존 프로젝트에 저장된 컴파일러는 그 프로젝트의 선택으로 그대로 남습니다.

자체 엔진이 없는, [제자리에서 연 폴더](/docs/library/#folders-opened-in-place)는 신뢰하고 나면 기본값을 따릅니다. 그 전에는 Tectonic으로 표시되고 컴파일됩니다. 어느 쪽이든 Oleafly는 그 폴더에 아무것도 쓰지 않습니다.

Typst는 **설정 → 엔진 → Typst**를 열고 기본 버전을 선택하세요. 새 Typst 프로젝트는 만들 때 기본값인 버전을 고정합니다. 나중에 기본값을 바꿔도 기존 프로젝트는 옮겨지지 않습니다.

## 현재 프로젝트의 컴파일러 바꾸기

[프로젝트 도구 모음](/docs/project-toolbar/)에서 **다시 컴파일** 옆의 화살표를 엽니다. LaTeX 프로젝트에서는 **컴파일러(이 프로젝트)** 아래에서 Tectonic, 자동, pdfLaTeX, XeLaTeX, LuaLaTeX 중 하나를 고른 다음 컴파일하세요. 템플릿이 선택한 설치에 없는 패키지나 글꼴을 요구하면 로그를 읽어 보세요.

Typst 프로젝트에서는 같은 메뉴에 **Typst 버전(이 프로젝트)** 항목이 대신 나타납니다. 설치된 버전을 고르거나, 설정을 따르려면 **기본**을 고르세요. 이 메뉴의 **엔진(이 프로젝트)** 그룹에서는 문서를 **Typst**와 **Calepin** 사이에서 전환합니다.

## 기존 TeX 배포판 감지

**설정 → 엔진 → LaTeX**을 열어 감지된 툴체인을 확인하세요. Oleafly는 `latexmk`와 보조 도구를 포함해 컴파일러 구성이 완전한지 확인합니다. 일부만 갖춘 시스템 설치는 정상 동작하는 관리형 설치보다 우선하지 않습니다.

## 관리형 TinyTeX 설치

전통적인 컴파일러가 필요한데 없다면 LaTeX 엔진 설정의 설치 컨트롤을 사용하세요. Oleafly는 `~/.oleafly/tinytex` 아래에 자체 TinyTeX를 내려받아 설치하며, 관리자 권한은 필요하지 않습니다. 처음 다운로드에 약 250 MB, 패키지에 추가 공간을 확보해 두세요.

## 패키지 관리

LaTeX 엔진 설정의 패키지 목록에서는 패키지를 필터링하고, 설명을 살펴보고, 추가하거나 제거할 수 있습니다. 태깅 배지는 태그된 PDF를 만들 때 추가로 신경 써야 하는 패키지를 알려 줍니다. 이 컨트롤은 `latexmk`가 쓰는 TeX 배포판을 관리하며, Tectonic에는 별도의 캐시가 있습니다.

[LaTeX 패키지와 태그된 PDF 가이드 읽기 →](/docs/latex-engines/)