> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/pandoc-hui-ru-yu-hui-chu.md).

# Pandoc 匯入與匯出

### Pandoc 匯入 / 匯出

Overleaf 可以使用 [Pandoc](https://pandoc.org/)將文件轉換為 LaTeX，反之亦然。轉換會在一個 **受沙箱保護的 Docker 容器** 由該 `clsi` 服務，因此此功能預設為關閉，必須透過幾個環境變數來啟用。

#### 功能說明

| 方向     | 從 → 到         | 格式                         | 位置                                                     |
| ------ | ------------- | -------------------------- | ------------------------------------------------------ |
| **匯入** | 文件 → LaTeX 專案 | `docx`, `markdown`         | *新專案 → 匯入* （上傳一個 `.docx` / `.md` 並將其轉換成可編輯的 `.tex` 專案） |
| **匯出** | LaTeX 專案 → 文件 | `docx`, `markdown`, `html` | *選單 → 下載 / 匯出* （透過 Pandoc 轉譯此專案）                       |

***

### 環境變數

有 **兩個** 變數，以及一個看起來相似但其實 **不要**.

1\. `ENABLE_PANDOC_CONVERSIONS` — 主開關

```bash
ENABLE_PANDOC_CONVERSIONS=true
```

* 類型：布林值（`true` 啟用；其他任何值都會停用）。
* **必須同時在兩個 `web` 以及 `clsi` 服務上設定。** 它們是彼此獨立的程序，具有各自的設定：
  * `web` 將其讀入 `enablePandocConversions` (`services/web/config/settings.defaults.js`）。它會限制匯入路由、匯出路由，以及 `ol-ExposedSettings.enablePandocConversions` 標誌，告訴前端是否要顯示匯入/匯出介面。
  * `clsi` 將其讀入 `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`）。它會限制執行 Pandoc 的端點。
* 如果它在 `web` 上啟用，但在 `clsi` （或反之）上沒有啟用，介面會出現，但轉換會失敗——請保持兩邊同步。

2\. `PANDOC_IMAGE` — clsi 用來進行轉換的容器映像

```bash
PANDOC_IMAGE=your-repo/pandoc:3.9
```

### 先決條件

因為轉換是以 Docker 容器的形式執行，而這些容器由 `clsi`:

1. **`clsi` 必須以沙箱模式執行，並可存取 Docker。** 在開發堆疊中 `clsi` 已經具有 `SANDBOXED_COMPILES=true` 以及主機 Docker socket（`/var/run/docker.sock`) 已掛載。
2. **此 `PANDOC_IMAGE` 必須存在** 在該 Docker 主機上（先前拉取或於本機建置）於第一次轉換前。

***

### 快速設定

開發堆疊（`develop/dev.env`）已預先附帶：

```bash
ENABLE_PANDOC_CONVERSIONS=true
PANDOC_IMAGE=overleaf-pandoc:local
```

由於官方映像是私有的，請先建置內建的映像 **一次** ，再使用此功能：

```bash
docker build -t overleaf-pandoc:local develop/pandoc
```

然後（重新）啟動堆疊，讓 `clsi` 以及 `web` 載入這些變數。

***

### 建置 Pandoc 映像

標準的 Pandoc 映像即可運作，因為 clsi 會以通用方式呼叫 Pandoc（沒有自訂樣板/過濾器）。它只需要三個執行時基本要素，全部都由 `develop/pandoc/Dockerfile`:

```dockerfile
# clsi 沙箱轉換用的自訂 Pandoc 映像
# （匯入/匯出：docx / markdown / html，透過 ENABLE_PANDOC_CONVERSIONS）。
#
# 為什麼需要這個：
#   官方的 quay.io/sharelatex/pandoc:3.9 映像是私有的（401，無法拉取）。
#   clsi 以通用方式呼叫 pandoc（沒有自訂樣板/過濾器/參考文件），因此
#   標準的 pandoc 映像即可運作——它只需要 clsi 所假設的三個執行時基本要素：
#
#   1. 不要有 `pandoc` ENTRYPOINT —— clsi 會執行 Cmd ["pandoc", ...]；若使用預設的
#      entrypoint，會變成 `pandoc pandoc ...`。
#   2. `zip` —— 匯入轉換的第二步會執行 `zip -r` 來打包輸出。
#   3. 使用者要與 clsi 執行轉換容器的方式一致（User=$TEXLIVE_IMAGE_USER）：
#        - UID 1000 的 `tex` —— 開發 / microservices 預設。
#        - UID 33 的 `www-data` —— Server Pro 沙箱化 *同層* 容器會設為
#          TEXLIVE_IMAGE_USER=www-data（見 /etc/overleaf/env.sh）。clsi（以
#          www-data）執行）會建立擁有者為 33:33 的轉換目錄，因此容器必須以
#          www-data(33) 身分執行才能寫入——否則 pandoc 會失敗，錯誤可能是
#          "unable to find user www-data" 或 "permission denied"。
#      Alpine 已經自帶一個 GID 為 82 的 `www-data` 群組，因此我們將其移到 GID 33，以
#      符合主機/texlive 映像。
#
# 建置（tag 必須與 develop/dev.env 中的 PANDOC_IMAGE 相符）：
#   docker build -t overleaf-pandoc:local develop/pandoc
#
# 注意：固定為 `latest`（撰寫時為 pandoc 3.10）。若要可重現的建置，請固定到特定的
# pandoc/core 標籤。
FROM pandoc/core:latest

ENTRYPOINT []

RUN apk add --no-cache zip \\
 && adduser -D -u 1000 tex \\
 && (delgroup www-data 2>/dev/null || true) \\
 && addgroup -g 33 www-data \\
 && adduser -D -u 33 -G www-data www-data
```

建置並加上標籤，使該標籤與 `PANDOC_IMAGE`:

```bash
docker build -t overleaf-pandoc:local develop/pandoc
```

在正式環境中，請將 `pandoc/core` 固定到特定版本，而不是 `latest` 以獲得可重現的建置，並將 `PANDOC_IMAGE` 設定為你的 registry 路徑。

***

### 疑難排解

| 症狀                              | 可能原因                                                                      |
| ------------------------------- | ------------------------------------------------------------------------- |
| 匯入/匯出按鈕沒有出現                     | `ENABLE_PANDOC_CONVERSIONS` 不要 `true` 中的 **web**                          |
| 介面有出現，但轉換時發生伺服器錯誤               | `ENABLE_PANDOC_CONVERSIONS` 未在 **clsi**執行，或 `PANDOC_IMAGE` 在 Docker 主機上缺少 |
| `clsi` 拉取映像時發生錯誤（401）           | `PANDOC_IMAGE` 仍指向私有的預設值；請建置/指向你自己的映像                                     |
| 容器執行時變成 `pandoc pandoc …` ／參數錯誤 | 映像具有一個 `pandoc` `ENTRYPOINT`；請使用 `ENTRYPOINT []`                          |
| 匯入輸出為空白 / zip 步驟失敗              | `zip` 未安裝在映像中                                                             |
| 轉換後檔案出現權限錯誤                     | 映像沒有 `tex` UID 1000 的使用者                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/pandoc-hui-ru-yu-hui-chu.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.