# 选择文档引擎

了解 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

模板要求使用 **LuaLaTeX**、基于 Lua 的排版，或要使用 Oleafly 的带标签 PDF 工作流时，请选择它。带标签的 PDF 含有文档结构，辅助技术可以利用。请运行[预检](/docs/preflight/)来检查结果；仅凭编译器的选择无法保证标签的质量。

## Typst

Oleafly 内置 Typst 0.15.1。创建一个 Typst 项目，在 `.typ` 文件中写作，然后点击 **重新编译**。无需安装任何 TeX。

**设置 → 引擎 → Typst** 还可以安装 Typst 0.11 到 0.15，也可以使用你电脑上已安装的 Typst。每个项目都固定自己的版本，所以 Oleafly 升级到较新的 Typst 时，论文的版式保持不变。文档第一次导入 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/)