选择文档引擎
了解 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”的部分模板要求使用 LuaLaTeX、基于 Lua 的排版，或要使用 Oleafly 的带标签 PDF 工作流时，请选择它。带标签的 PDF 含有文档结构，辅助技术可以利用。请运行预检来检查结果；仅凭编译器的选择无法保证标签的质量。
Typst
标题为“Typst”的部分Oleafly 内置 Typst 0.15.1。创建一个 Typst 项目，在 .typ 文件中写作，然后点击 重新编译。无需安装任何 TeX。
设置 → 引擎 → Typst 还可以安装 Typst 0.11 到 0.15，也可以使用你电脑上已安装的 Typst。每个项目都固定自己的版本，所以 Oleafly 升级到较新的 Typst 时，论文的版式保持不变。文档第一次导入 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 有单独的缓存。