選擇文件引擎
了解 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 專案。
Tectonic
標題為「Tectonic」的段落想要簡單的 LaTeX 環境，請使用 Tectonic。它隨 Oleafly 提供，會下載建置所需的 TeX 套件，並快取起來供之後的建置使用。如果你的範本沒有指定特定編譯器，就從這裡開始。
旅行前請在連線時先編譯一次。已快取的專案可以離線編譯；新的套件可能仍需要下載。啟用 設定 → 一般 → 離線模式，就能讓 Tectonic 使用它的快取。
pdfLaTeX
標題為「pdfLaTeX」的段落出版社或既有專案指定時，請選擇 pdfLaTeX。它遵循傳統的 LaTeX 工作流程，適合搭配較舊的文件類別與套件組合。它需要安裝含有 latexmk 的 TeX 發行版。
XeLaTeX
標題為「XeLaTeX」的段落專案要求時請選擇 XeLaTeX，特別是使用 fontspec、OpenType 字型或多語言文字的專案。請確認原始碼所指定的字型已安裝，或已隨專案一起提供。它同樣透過 latexmk 執行。
LuaLaTeX
標題為「LuaLaTeX」的段落範本要求、使用以 Lua 為基礎的排版，或要用 Oleafly 的標記式 PDF 工作流程時，請選擇 LuaLaTeX。標記式 PDF 帶有輔助科技可以使用的文件結構。請執行 預檢 來檢查結果；光靠選擇編譯器並不能保證標記的品質。
Typst
標題為「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」的段落Markdown 使用 Pandoc 準備排版後的文件，再用 Tectonic 建置 PDF。Pandoc 缺少時，請開啟 設定 → 引擎 → Markdown 安裝。接著開啟你的 Markdown 專案並編譯。
標題、清單、數學式和視覺化編輯器，請參閱 Markdown 寫作。匯出指南 說明專案提供哪些輸出格式。
Quarto
標題為「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」的段落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 文件中的程式碼會以你的權限執行，所以在你允許之前，每個專案的程式碼都是關閉的。在需要程式碼的編譯之後，編輯器上方的橫幅會說明程式碼已關閉，並提供 在此專案中允許程式碼。你也可以開啟 重新編譯 旁邊的箭頭，並在 程式碼（這台電腦） 下選擇 在這台電腦上執行程式碼。關閉 會再把它關掉。只有在你信任專案中的每個檔案時，才允許程式碼。
這項選擇只適用於這台電腦。它不會儲存在專案中，變更專案的引擎也會讓程式碼再次關閉。在共用專案中，Oleafly 會再詢問一次，因為任何能編輯專案的人都可以變更它的程式碼。
程式碼關閉時：
- Quarto 會顯示每個程式碼區塊的程式碼，但不執行。篩選器、短代碼、
_extensions、算繪前與算繪後的指令碼，以及行內 R 程式碼，即使這時也會執行程式碼，所以使用它們的文件在你允許程式碼之前無法編譯。 - Calepin 無法略過程式碼。Oleafly 會根據 Calepin 上次執行時儲存的結果，用一般的 Typst 建置 PDF。如果沒有任何結果，編譯就會停止，並請你允許程式碼。
你原地開啟的資料夾也必須先受到信任，Quarto 或 Calepin 才能編譯它。這兩種引擎都不支援原始碼與 PDF 同步。
為新專案設定預設值
標題為「為新專案設定預設值」的段落開啟 設定 → 引擎 → LaTeX，選擇 預設編譯引擎：Tectonic（內建） 或 latexmk（系統 TeX）。之後你建立的每個 LaTeX 專案都會從它開始：
- 從 新增專案 對話框建立的空白專案或範本，以及研究專案。
- 匯入的 ZIP、資料夾、arXiv 論文或 GitHub 儲存庫。
- 你轉換成 LaTeX 專案的文件，例如 Word 檔案或 PDF。
引擎會寫入專案的 project.json，所以共同作者開啟專案時會以相同方式編譯。匯入的專案若指定 pdfLaTeX、XeLaTeX 或 LuaLaTeX，改用 latexmk 後仍會保留該編譯器。既有專案儲存的編譯器仍是它自己的選擇。
你 原地開啟 且沒有自己引擎的資料夾，會在你信任它之後跟隨預設值。在那之前，它會以 Tectonic 顯示與編譯。不論哪種情況，Oleafly 都不會在該資料夾中寫入任何東西。
對於 Typst，請開啟 設定 → 引擎 → Typst 並選擇預設版本。新的 Typst 專案會鎖定建立當下的預設版本。之後變更預設值，不會移動既有的專案。
變更目前專案的編譯器
標題為「變更目前專案的編譯器」的段落開啟 專案工具列 中 重新編譯 旁邊的箭頭。在 LaTeX 專案中，於 編譯器（本專案） 下選擇 Tectonic、自動、pdfLaTeX、XeLaTeX 或 LuaLaTeX，然後編譯。如果範本需要所選安裝中沒有的套件或字型，請查看記錄。
在 Typst 專案中，同一個選單改為提供 Typst 版本（本專案）。請選擇已安裝的版本，或選 預設 以跟隨設定。它的 引擎（本專案） 群組可以把文件在 Typst 與 Calepin 之間切換。
偵測既有的 TeX 發行版
標題為「偵測既有的 TeX 發行版」的段落開啟 設定 → 引擎 → LaTeX，查看偵測到的工具鏈。Oleafly 會檢查是否有完整的編譯器組合，包括 latexmk 和相關的輔助工具。不完整的系統安裝，不會優先於運作正常的託管安裝。
安裝託管的 TinyTeX
標題為「安裝託管的 TinyTeX」的段落如果你需要傳統編譯器卻沒有安裝，請使用 LaTeX 引擎設定中的安裝控制項。Oleafly 會把它自己的 TinyTeX 下載到 ~/.oleafly/tinytex，不需要管理員權限。初次下載請預留約 250 MB，套件另需額外空間。
管理套件
標題為「管理套件」的段落LaTeX 引擎設定中的套件清單，可以讓你篩選套件、查看說明，以及新增或移除套件。標記徽章會指出在產生標記式 PDF 時需要多加留意的套件。這些控制項管理的是 latexmk 所使用的 TeX 發行版；Tectonic 有它自己獨立的快取。