# 選擇文件引擎

了解 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、網頁或投影片。Oleafly 找到你電腦上的 Quarto 時會使用它。如果沒有，請開啟 **設定 → 引擎 → 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 會建置網頁。指定了 R Markdown `output:`（例如 `pdf_document`）的 `.Rmd` 檔案，會取得對應的 Quarto 格式。

程式碼會在你電腦上已有的 R、Python 或 Julia 中執行。Oleafly 從不安裝它們，同一個設定分頁中的 **語言** 會顯示它找到的語言。Python 程式碼還需要該 Python 中裝有 Jupyter。匯出提供 DOCX 和 HTML，兩者都由 Quarto 算繪。**新增專案** 對話框有兩個 Quarto 範本：**Quarto article** 是透過 Typst 建置的 PDF，**Quarto slides** 是 reveal.js 投影片。

## Calepin

Calepin 會執行 Typst 文件中的程式碼，並把結果放進 PDF。Calepin 文件是匯入 `/.calepin/calepin.typ` 的 `.typ` 檔案。你可以從 **Calepin report** 範本開始，或在 Typst 專案中開啟 **重新編譯** 旁邊的箭頭，並在 **引擎（本專案）** 下選擇 **Calepin**。

請以和 Quarto 相同的方式，從 **設定 → 引擎 → Calepin** 用 **下載 Calepin 0.0.61** 安裝。Calepin 使用 Oleafly 內建的 Typst 建置。如果某個程式碼區塊的語言沒有安裝，那裡會顯示一段簡短的說明，文件的其餘部分仍會建置。匯出提供 HTML，由 Calepin 算繪。

## 在專案中允許程式碼

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 儲存庫。
- 你轉換成 LaTeX 專案的文件，例如 Word 檔案或 PDF。

引擎會寫入專案的 `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 會把它自己的 TinyTeX 下載到 `~/.oleafly/tinytex`，不需要管理員權限。初次下載請預留約 250 MB，套件另需額外空間。

## 管理套件

LaTeX 引擎設定中的套件清單，可以讓你篩選套件、查看說明，以及新增或移除套件。標記徽章會指出在產生標記式 PDF 時需要多加留意的套件。這些控制項管理的是 `latexmk` 所使用的 TeX 發行版；Tectonic 有它自己獨立的快取。

[閱讀 LaTeX 套件與標記式 PDF 指南 →](/docs/latex-engines/)