> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/pandoc-import-and-export.md).

# Pandoc 匯入與匯出

### Pandoc 匯入 / 匯出

Overleaf 可以使用以下工具將文件與 LaTeX 互相轉換： [Pandoc](https://pandoc.org/)。轉換會在一個 **沙箱化的 Docker 容器中** 由 `clsi` 服務管理，因此此功能預設為關閉，必須透過幾個環境變數啟用。

#### 功能說明

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

***

### 環境變數

共有 **兩個** 重要的變數，另外還有一個外觀相似但不具作用的變數 **不要**.

1\. `ENABLE_PANDOC_CONVERSIONS` — 總開關

```bash
ENABLE_PANDOC_CONVERSIONS=true
```

* 類型：布林值（`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 映像
#（透過 ENABLE_PANDOC_CONVERSIONS 進行匯入／匯出：docx / markdown / html）。
#
# 為什麼需要這個：
#   官方 quay.io/sharelatex/pandoc:3.9 映像是私有的（401，無法拉取）。
#   clsi 會以通用方式呼叫 pandoc（沒有自訂範本／過濾器／reference-doc），因此一個
#   標準的 pandoc 映像即可運作——它只需要 clsi 所假設的三個執行時必要項目：
#
#   1. 不要有 `pandoc` ENTRYPOINT——clsi 會執行 Cmd ["pandoc", ...]；若使用預設
#      的 entrypoint，命令就會變成 `pandoc pandoc ...`。
#   2. `zip`——匯入轉換的第二步會執行 `zip -r` 來打包輸出。
#   3. 使用者要符合 clsi 執行轉換容器的方式（User=$TEXLIVE_IMAGE_USER）：
#        - UID 1000 的 `tex`——開發／微服務預設值。
#        - UID 33 的 `www-data`——Server Pro 沙箱化 *同層* 容器會設定
#          TEXLIVE_IMAGE_USER=www-data（請見 /etc/overleaf/env.sh）。clsi（以
#          www-data 執行）會建立擁有者為 33:33 的轉換目錄，因此容器必須以
#          www-data(33) 身分執行才能寫入——否則 pandoc 會因以下任一情況而失敗：
#          「無法找到使用者 www-data」或「權限被拒絕」。
#      Alpine 內建的 `www-data` 群組 GID 為 82，因此我們將其移到 GID 33，以
#      與主機／texlive 映像一致。
#
# 建置（標籤必須與 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://ayakaleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/pandoc-import-and-export.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.