# 导出与转换项目

保存最新的 PDF，打包可编辑的源码，导出页面图片或 HTML，用 Typst 生成 PDF/A 和 PDF/UA，或转换 LaTeX、Typst 或 Markdown 文档。

打开项目工具栏中的 **导出**。菜单会跟随当前的文档引擎和类型，所以只显示 Oleafly 能为该项目执行的路径。

![导出是顶部项目栏中紧接在重新编译之后的下载控件。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1282,0,232,48)

## 按收件人的需要选择输出

- **PDF** 用于阅读、打印和大多数投稿系统。
- **源码 ZIP** 用于需要稿件、图片、参考文献和本地样式的合作者或系统。
- **页面 PNG** 用于需要图片的幻灯片、消息或评审系统。
- **由 Typst 写出的 PNG、SVG 或 HTML** 用于需要逐页图片、矢量页面或网页的 Typst 项目。
- **Word、HTML、Markdown、Typst、LaTeX 或纯文本** 用于需要在其他格式中编辑或复用内容的人。
- **PowerPoint** 用于把演示文稿或 Markdown 文档转成幻灯片。**EPUB** 用于电子书阅读器。具体出现哪些取决于引擎。参见[演示文稿与图书导出](#presentation-and-book-exports)。

## 保存 PDF、源码归档或页面图片

1. 选择 **重新编译**，让输出包含你最新的修改。
2. 检查 PDF，包括最后几页和参考文献。
3. 打开 **导出**。
4. 选择 **导出为 PDF**、**导出源码 (.zip)** 或 **将页面导出为 PNG**。
5. 在保存对话框中选一个保存位置。
6. 在完成提示中选择 **在文件夹中显示**，找到保存的文件。

在项目有了 PDF 之前，PDF 和页面图片相关的操作保持禁用，菜单会显示 **PDF 需要先编译**。**导出为 PDF** 会保存预览中显示的 PDF。**将页面导出为 PNG** 会以高分辨率保存你在预览中查看的页面。

源码归档不包含构建缓存和 Git 内部文件。它也不包含符号链接，完成提示会说明跳过了多少个。

### PDF 不是最新时

预览已经过期时，Oleafly 仍会保存 PDF 或页面图片，并在完成提示中告诉你：

- 编译失败之后，提示会说上次编译失败了，所以文件可能不完整。
- 有尚未编译的修改时，提示会说文件来自上次编译，不包含你最新的修改。

把文件发给任何人之前，请重新编译、检查预览，然后再导出一次。

## Typst 图片和 HTML

Typst 项目的导出菜单里还有 **图片和 HTML**，它会打开 **用 Typst 导出**。这些文件由 Typst 自己绘制，所以 PNG 和 SVG 页面与 PDF 完全一致。

- **PNG 图片** 可设置 **分辨率**：72、144、300 或 600 PPI。
- **SVG 图片** 把页面保留为矢量图形。
- **HTML** 标记为 **实验性**。Typst 的 HTML 保留文字和图片，但不包含页面设置和绘图。在 Typst 0.15 之前它也不包含公式，选择 HTML 时对话框会这样说明。

对于 PNG 和 SVG，**页面** 接受页码和范围，例如 `1, 3-5` 或 `8-`。留空则导出所有页面。每一页都保存为单独的文件，并在你选择的名称后加上编号。页面范围需要 Typst 0.12 或更高版本，HTML 需要 Typst 0.13 或更高版本。对话框只提供项目的 Typst 版本能做到的选项。如果项目有[构建变体](/docs/typst/#build-variants-and-sysinputs)，导出会使用编译菜单中选定的那一个。

## 用 Typst 生成 PDF/A 和 PDF/UA

Typst 自己写出归档用和无障碍的 PDF。打开项目侧栏中用于[预检](/docs/preflight/)的 **盾牌**，在 **无障碍** 检查下找到 **PDF 标准**。选择一个 **标准**，例如 PDF/A-2b 或 PDF/UA-1，然后选择 **导出 PDF**。

可选的列表取决于项目的 Typst 版本。Typst 0.11 没有可选项，Typst 0.12 提供 PDF/A-2b，Typst 0.13 增加了 PDF/A-3b，Typst 0.14 及更高版本提供所有 PDF/A 级别以及 PDF/UA-1。Typst 0.14 及更高版本还会给每个 PDF 加上供屏幕阅读器使用的标签，所以没有单独的带标签编译。PDF/UA-1 需要文档标题，并要求每张图片都有替代文本，预检会检查这两项。

## 可编辑格式

| 项目引擎 | 导出中的格式 |
| --- | --- |
| **LaTeX** | Word、带 MathML 的独立 HTML、Markdown、Typst 和纯文本 |
| **Typst** | LaTeX、Word、带 MathML 的独立 HTML、Markdown 和纯文本 |
| **Markdown** | Word、带 MathML 的独立 HTML、Typst、LaTeX 和纯文本 |

Typst 项目还提供 EPUB，Markdown 项目还提供 PowerPoint 和 EPUB。LaTeX 项目只有在文档类匹配时才提供它们。

这些转换通过 Pandoc 在本地运行。Oleafly 会使用你电脑上兼容的安装，或在第一次需要时下载经过验证的托管版本。

Typst 项目走的是另一条路径。Typst 先把文档写成 HTML，再由 Pandoc 把这份 HTML 转成 Word、HTML、Markdown、LaTeX、纯文本或 EPUB，因此公式和引用都能保留。文档能否走这条路径，取决于项目的 Typst 版本：

| Typst 版本 | 路径 |
| --- | --- |
| 0.15 或更高 | 通过 HTML |
| 0.13 和 0.14 | Typst 能写出整份文档时通过 HTML。不能时，Pandoc 改为读取 Typst 源文件。 |
| 0.12 或更早 | Pandoc 读取源文件 |

如果 Typst 在写出 HTML 时出错停止，任何版本上 Pandoc 都会改为读取源文件。在 Typst 0.13 或 0.14 上由 Pandoc 读取源文件时，除非导出有警告，否则完成提示会警告旋转、缩放、移动或倾斜的文字可能缺失。要获得最完整的导出，请在编译菜单的 **Typst 版本（本项目）** 下把项目切换到 Typst 0.15 或更高版本。

当导出通过 HTML 进行时，`align`、`grid` 和 `rotate` 等布局函数中的文字会保留。用 CeTZ 绘制的图会丢失线条和形状，只保留文字标签，完成提示会指出 Typst 省略了什么。

## 转换文档

1. 先编译一次，并修复所有源码错误。
2. 打开 **导出**，选择目标格式。
3. 如果出现提示，完成 Pandoc 的设置。如果 Oleafly 说 Pandoc 不可用，请在 **设置 → 引擎 → Markdown** 中选择 **修复 Pandoc**，然后再次导出。
4. 用建议的扩展名保存转换后的文件。
5. 阅读完成提示。如果它提到警告，请选择 **显示警告**，查看导出遗漏了什么。
6. 在目标应用中打开该文件，检查结构和外观。

想快速测试的话，可以导出一小节，其中包含标题、公式、表格、图片和引用。如果这五项都能顺利保留，再转换整篇稿件并再次检查。

如果要把整个 LaTeX 项目变成可以继续写作的 Typst 项目，请改用[转换为 Typst 项目](/docs/typst/#convert-a-latex-project-to-typst)。它会创建一个新项目，并报告需要注意的地方。

### 转换会保留什么

Pandoc 的目标是保留标题、段落、列表、链接、引用、表格、图片和可编辑的数学公式。它无法在每种目标格式中重现源语言的所有功能。请重点检查这些方面：

- 自定义的 LaTeX 命令和环境
- 手工调整的页面布局或浮动体
- 复杂或嵌套的表格
- 参考文献样式和引用的呈现
- 在目标中没有直接对应项的 Typst 函数
- 原始 HTML 或 Markdown 扩展

HTML 导出会嵌入它的资源，并把公式写成 MathML。这样很适合分享需要独立打开的文档，但仍然值得在读者使用的浏览器中测试。

### 各种格式保留什么

- Word 和 PowerPoint 导出会把 PDF、SVG 和 WebP 图片转成 220 ppi 的 PNG 图片。源码中没有指定尺寸的图片保持自己的宽度。
- HTML 和 EPUB 导出会把 PDF 图片转成 PNG 图片。
- 从 LaTeX 导出的 Markdown 和纯文本保留标题、作者和摘要。
- 从 LaTeX 导出到 Markdown 或 Typst，以及从 Markdown 导出到 LaTeX 或 Typst 时，会链接到项目的图片文件，而不是复制它们。除非导出有警告，否则完成提示会提醒你，在编译导出的文件之前，先把图片和参考文献复制到它旁边。导出到 Typst 或 LaTeX 的 Markdown 文档会保留它声明的参考文献；如果没有声明，则保留项目的 `.bib` 文件。
- Markdown 文档导出的 LaTeX 会遵循它的[文档类型](/docs/writing/markdown/#document-types)。幻灯片和海报会变成 Beamer 源码，报告或图书以 `#` 标题开始每一章，信函会变成 KOMA-Script 信函。
- 从 Typst 导出的 LaTeX 会把文档的图片复制到 `.tex` 文件旁边的 `<name>-media` 文件夹中。SVG、GIF 和 WebP 图片在那里会变成 PDF，因为 LaTeX 无法读取它们。

导出会在主文档所在的文件夹、项目根目录和所有 `\graphicspath` 文件夹中查找图片，也能找到不带扩展名的图片名称。EPS 图片无法转换，所以会原样放进文件，并附带警告。在 Markdown 文档导出的 Word、HTML、EPUB 或 PowerPoint 中，Mermaid 代码块会显示为它保存好的图片。

### 导出后的警告

Pandoc 会略去格式无法容纳的内容。当 LaTeX 或 Markdown 项目的导出，或读取源文件的 Typst 导出出现这种情况时，完成提示会说明文件是带警告保存的以及警告数量，并取代它的其他说明，例如复制图片的提醒。选择 **显示警告** 会打开 **导出警告**，列出缺失的内容。该对话框中的 **在文件夹中显示** 会打开保存文件所在的文件夹。

列表可能指出：

- 导出遗漏的某个块，已知时附带文件和行号，例如 `tikzpicture`、`\includepdf`，或 `\only`、`\uncover` 这样的 Beamer 叠加命令
- 导出找不到或无法转换的图片
- 不在参考文献中的引用键
- 仍保留为 TeX 代码的数学公式
- 还没有编号的引用，编译一次即可解决

重复的警告只显示一次，列表最多 50 条。图片缺失时，PowerPoint 导出的做法不同：它会停止，不保存文件，错误中会指出该图片。通过 HTML 的 Typst 导出，则改在完成提示中说明 Typst 省略了什么。

## 演示文稿与图书导出

LaTeX 项目根据文档类来匹配这些导出。Beamer 演示文稿会出现 **导出为 PowerPoint (.pptx)**，`book`、`report`、`memoir`、`scrbook` 和 `scrreprt` 类会出现 **导出为 EPUB (.epub)**。

在 Beamer 演示文稿中，每个 frame 开始一张新幻灯片，`\section` 添加一张章节幻灯片，`\subsection` 不添加。含有多张图片，或同时含有图片和其他内容的 frame，可能会延伸到第二张幻灯片。

在 Typst 和 Markdown 项目中，菜单不会为这些导出检查文档。Markdown 项目始终提供这两项，Typst 项目始终提供 EPUB。Markdown 文档转成 PowerPoint 时，每个一级标题成为一张章节幻灯片，每个二级标题开始一张新幻灯片。例外是带有 `type: slides` 的文档：它 front matter 中的 `slide-level` 一行决定由哪一级标题开始一张幻灯片。每个 EPUB 都会生成目录，其中的公式是 MathML。

请把它们当作可编辑的起点。幻灯片的构图和图书的排版很少能在格式之间一一对应，所以请在目标应用中检查每一张幻灯片或每一章。

## 导出独立图片

独立图片项目在编译后提供 **导出为 PDF（矢量图）** 和 **导出为 PNG**。需要在任何缩放比例下都保持线条和文字清晰时，选 PDF。目标只接受位图时，选 PNG。

## 把输出保存在项目内

[PDF 预览](/docs/pdf-preview/)还提供 **将 PDF 保存到项目**。这样可以把投稿用的副本或编译好的图片放在源码旁边。要让这份副本保持最新，请在同一个菜单中打开[编译时同步 PDF](/docs/pdf-preview/#sync-pdf-on-compiles)，每次编译成功后，Oleafly 都会刷新一个以项目命名的 PDF。较早的 PDF 可以从[检查点](/docs/checkpoints/#save-a-pdf-from-a-checkpoint)保存，而无需恢复项目。只有在你打算对生成的输出做版本管理时，才把该文件加入 [Git 历史](/docs/git-history/)。

## 分享前检查

投稿前运行[预检](/docs/preflight/)。如果需要带标签的 PDF，请按 LaTeX 的无障碍导出流程操作，或在 Typst 项目中选择 PDF/UA 标准，然后用独立的 PDF/UA 检查器和人工无障碍审查来验证结果。预检会检查许多有用的信号，但它不能认证是否合规。
