# 匯出與轉換專案

儲存最新的 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 專案會依文件類別對應這些匯出。**匯出為 PowerPoint（.pptx）** 會出現在 Beamer 簡報上，**匯出為 EPUB（.epub）** 則出現在 `book`、`report`、`memoir`、`scrbook` 和 `scrreprt` 類別。

在 Beamer 簡報中，每個 frame 會開啟新的投影片，`\section` 會加入章節投影片，`\subsection` 則不會。有多張圖片，或有圖片加其他內容的 frame，可能會延伸到第二張投影片。

在 Typst 和 Markdown 專案中，選單不會檢查文件來決定提供這些匯出。Markdown 專案一律同時提供兩者，Typst 專案則一律提供 EPUB。Markdown 文件轉成 PowerPoint 時，每個第 1 級標題會變成章節投影片，每個第 2 級標題會開啟新的投影片。例外是帶有 `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 檢查工具和人工的無障礙審查來驗證結果。預檢會檢查許多有用的訊號，但它不能保證符合規範。
