跳转到内容
Oleaflyv0.4.12

了解 LaTeX、Typst、Markdown、Quarto 和 Calepin 文档如何变成 PDF,并为你的项目选择所需的编译器。

引擎把你的源文件变成读者阅读的文档。创建项目时选择文档语言。对于 LaTeX 项目,你还可以选择由哪个 LaTeX 编译器来执行构建。

每种文档语言如何变成 PDFLaTeX 源码用内置的 Tectonic 引擎编译,或用 latexmk 配合系统 TeX 发行版或 Oleafly 管理的 TinyTeX 编译。Typst 源码用内置的 Typst 或项目锁定的版本编译。Markdown 源码先经过 Pandoc 转换为 LaTeX,再由 Tectonic 生成 PDF。LaTeXTypstMarkdownTectonic内置latexmk系统 TeX 或 TinyTeXTypst内置或项目锁定Pandoc转换为 LaTeXTectonic生成 PDFPDF每种文档语言如何变成 PDFLaTeX 源码用内置的 Tectonic 引擎编译,或用 latexmk 配合系统 TeX 发行版或 Oleafly 管理的 TinyTeX 编译。Typst 源码用内置的 Typst 或项目锁定的版本编译。Markdown 源码先经过 Pandoc 转换为 LaTeX,再由 Tectonic 生成 PDF。LaTeXTypstMarkdownTectonic内置latexmk系统 TeX或 TinyTeXTypst内置或项目锁定Pandoc转为 LaTeXTectonic生成 PDFPDF
LaTeX 用 Tectonic 或 latexmk 编译,Typst 用项目锁定的版本编译。Markdown 先经过 Pandoc,再交给 Tectonic。
Oleafly 在这台电脑上找到的 LaTeX 和 Typst 引擎及其版本。
Oleafly 在这台电脑上找到的 LaTeX 和 Typst 引擎及其版本。 打开完整截图
你的工作从这里开始如何变成 PDF
期刊投稿、成熟的学位论文文档类,或已有的 .tex 项目LaTeXTectonic,或通过 latexmk 运行的编译器
想用简洁排版语法写的新论文、报告或简历Typst内置的 Typst 0.15.1,或项目固定的其他 Typst 版本
文字草稿、笔记,或想导出为多种格式的文档MarkdownPandoc 把源文件转换为 LaTeX,再由 Tectonic 生成 PDF
分析报告、文章或幻灯片,其结果由 R、Python 或 Julia 代码生成QuartoQuarto 把 .qmd 或 .Rmd 文件渲染为 PDF、网页或幻灯片
带有代码块的 Typst 文档CalepinCalepin 运行代码,然后由内置的 Typst 构建 PDF

这个选择决定了编辑器工具栏、源码语法和可用的导出格式。更换 LaTeX 编译器并不会把文档翻译成 Typst 或 Markdown。要把 LaTeX 项目迁移到 Typst,请把它转换为新的 Typst 项目。

想要简单直接的 LaTeX 环境,就用 Tectonic。它随 Oleafly 一起提供,会下载构建所需的 TeX 宏包,并缓存起来供之后的构建使用。如果你的模板没有要求特定的编译器,就从它开始。

出行前,请在联网时先编译一次。已缓存的项目可以离线编译;新的宏包仍可能需要下载。启用 设置 → 通用 → 离线模式,让 Tectonic 使用它的缓存。

出版商或现有项目指定使用 pdfLaTeX 时,请选择它。它沿用传统的 LaTeX 工作流,适合较旧的文档类和宏包组合。它需要安装了 latexmk 的 TeX 发行版。如果这台电脑上没有,选择它时 Oleafly 会提议安装 TinyTeX。请参阅没有安装 TeX 时。

项目要求使用 XeLaTeX 时请选择它,尤其是使用 fontspec、OpenType 字体或多语言文本的项目。请确认源文件中指定的字体已经安装,或已包含在项目中。它同样通过 latexmk 运行。

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

日文文档请选择 upLaTeX 或 pLaTeX,例如基于 jsarticle 或 jlreq 的文档。自动 会为这些文档类自动选择它们。两者都需要 TeX Live 的日文支持,编译需要时,Oleafly 可以把它安装到 TinyTeX 中。请参阅日文文档。

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 使用 Pandoc 准备排版好的文档,再用 Tectonic 构建 PDF。如果缺少 Pandoc,请打开 设置 → 引擎 → Markdown 安装它。然后打开你的 Markdown 项目并编译。

标题、列表、数学公式和可视化编辑器请参阅 Markdown 写作。导出指南说明了项目提供哪些输出格式。

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 的其余部分。要在你自己的浏览器中打开它,请选择预览工具栏上的在浏览器中打开(地球图标)。

文档没有声明格式时,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 会运行 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 代码,即使在这时也会运行代码,所以使用它们的文档在你允许代码之前无法编译。pdf-engine 不是 pdflatex、xelatex、lualatex 或 typst 时也一样,例如 pdf-engine: tectonic。
  • Calepin 无法跳过代码。Oleafly 会根据 Calepin 上次运行时保存的结果,用普通的 Typst 构建 PDF。如果没有保存的结果,编译会停止,并请你允许代码。

你就地打开的文件夹也必须先被信任,Quarto 或 Calepin 才能编译它。这两种引擎都不支持源码与 PDF 同步。

打开 设置 → 引擎 → LaTeX,选择 默认编译引擎:Tectonic(内置) 或 latexmk(系统 TeX)。此后你创建的每个 LaTeX 项目都从它开始:

  • 来自 新建项目 对话框的空白项目或模板,以及研究项目。
  • 导入的 ZIP、文件夹、arXiv 论文或 GitHub 仓库。
  • 你转换成 LaTeX 项目的文档,例如 Word 文件或 PDF。

引擎会写入项目的 project.json,所以合作者打开项目时会以同样的方式编译。导入的项目如果指定了 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX,转到 latexmk 后仍保留该编译器。已有项目保存的编译器仍由它自己决定。

你就地打开的文件夹如果没有自己的引擎,在你信任它之后会跟随默认值。在此之前,它使用 Tectonic 显示和编译。无论哪种情况,Oleafly 都不会往文件夹里写入任何内容。

对于 Typst,打开 设置 → 引擎 → Typst 选择默认版本。新的 Typst 项目会固定创建时的默认版本。之后更改默认值,不会改动已有的项目。

在项目工具栏中,打开 重新编译 旁边的箭头。在 LaTeX 项目中,于 编译器(本项目) 下选择 Tectonic、自动、pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX,然后编译。如果这台电脑上没有可用的 TeX 发行版,对话框会提供 下载并使用 TinyTeX 或 切换回 Tectonic。如果模板需要所选安装中没有的宏包或字体,请查看日志。

在 Typst 项目中,同一个菜单里换成了 Typst 版本(本项目)。选择一个已安装的版本,或选择 默认 以跟随设置。其中的 引擎(本项目) 一组用于在 Typst 和 Calepin 之间切换文档。

打开 设置 → 引擎 → LaTeX,查看 管理 TeX 发行版。它会列出 Oleafly 找到的每一个发行版,包括你终端 PATH 上的那个,并把 latexmk 用于编译的那个标为 使用中。Oleafly 会检查是否有一套完整的编译器配置,包括 latexmk 和配套工具。不完整的系统安装不会优先于可用的托管安装。在另一个发行版上选择 用于编译,即可切换到它。

MiKTeX 需要 Perl 才能运行 latexmk。没有 Perl 时,MiKTeX 会显示 latexmk 需要 Perl。请参阅 MiKTeX 与 Perl。

如果你需要传统编译器但还没有,请选择 LaTeX 引擎设置中的 下载 TinyTeX(约 250 MB)。Oleafly 会下载它自己的 TinyTeX 安装,不需要管理员权限。请为首次下载预留大约 250 MB,随着模板添加宏包,最多会增长到约 1 GB。你可以取消下载,之后再继续;托管的 TinyTeX 比 Oleafly 期望的版本旧时,会出现 更新。在 Linux 上,请先安装 Perl。请参阅安装和更新 TinyTeX。

LaTeX 引擎设置中的宏包列表可以筛选宏包、查看说明,以及添加或移除宏包。标签徽章会标出生成带标签 PDF 时需要额外注意的宏包。这些控件管理的是 latexmk 使用的 TeX 发行版;Tectonic 有单独的缓存。来自 Debian、Ubuntu 或 Fedora 的 TeX Live 则改用 apt 或 dnf 管理,MiKTeX 用 MiKTeX Console 管理。

阅读 LaTeX 宏包与带标签 PDF 指南 →

图片预览

无法加载 AI 回答

请重试,或搜索文档。