문서 엔진 선택하기

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

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

LaTeX는 Tectonic이나 latexmk로, Typst는 프로젝트가 고정한 버전으로 컴파일됩니다. Markdown은 먼저 Pandoc을 거친 뒤 Tectonic을 거칩니다.

언어 고르기

작업	시작점	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 프로젝트로 변환하세요.

Tectonic

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

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

pdfLaTeX

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

XeLaTeX

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

LuaLaTeX

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

Typst

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

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

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

Markdown

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

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

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

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

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

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

제자리에서 연 폴더도 신뢰해야 Quarto나 Calepin이 컴파일할 수 있습니다. 두 엔진 모두 소스와 PDF 동기화를 지원하지 않습니다.

새 프로젝트의 기본값 설정

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

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

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

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

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

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

프로젝트 도구 모음에서 다시 컴파일 옆의 화살표를 엽니다. 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 가이드 읽기 →