> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pandoc 匯入與匯出

### Pandoc 匯入／匯出

Overleaf 可以使用 [Pandoc](https://pandoc.org/) 在 LaTeX 與其他文件格式之間互相轉換。轉換會在由 `clsi` 服務管理的**沙箱化 Docker 容器**中執行，因此此功能預設為關閉，需透過幾個環境變數來啟用。

#### 功能說明

| 方向 | 來源 → 目標 | 格式 | 位置 |
| - | - | - | - |
| **匯入** | 文件 → LaTeX 專案 | `docx`, `markdown` | *新增專案 → 匯入*（上傳 `.docx`／`.md` 並將其轉換為可編輯的 `.tex` 專案） |
| **匯出** | LaTeX 專案 → 文件 | `docx`, `markdown`, `html` | *選單 → 下載／匯出*（透過 Pandoc 轉譯專案） |

***

### 環境變數

有**兩個**變數是重要的，另有一個看起來相似但**無關**的變數。

1\. `ENABLE_PANDOC_CONVERSIONS` — 總開關

```bash theme={null}
ENABLE_PANDOC_CONVERSIONS=true
```

* 類型：布林值（`true` 表示啟用；其他任何值皆表示停用）。
* <strong>必須同時在 `web` 與 `clsi` 兩個服務上設定。</strong> 它們是各自獨立設定的獨立程序：
  * `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 theme={null}
PANDOC_IMAGE=your-repo/pandoc:3.9
```

### 先決條件

由於轉換是以 `clsi` 產生的 Docker 容器執行：

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

***

### 快速設定

開發堆疊（`develop/dev.env`）已內建：

```bash theme={null}
ENABLE_PANDOC_CONVERSIONS=true
PANDOC_IMAGE=overleaf-pandoc:local
```

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

```bash theme={null}
docker build -t overleaf-pandoc:local develop/pandoc
```

接著（重新）啟動堆疊，讓 `clsi` 與 `web` 讀取這些變數。

***

### 建置 Pandoc 映像檔

由於 clsi 以通用方式呼叫 Pandoc（不使用自訂範本／篩選器），因此標準的 Pandoc 映像檔即可運作。它只需要三項執行階段必要條件，全都由 `develop/pandoc/Dockerfile` 處理：

```dockerfile theme={null}
# Custom Pandoc image for clsi sandboxed conversions
# (import/export: docx / markdown / html, via ENABLE_PANDOC_CONVERSIONS).
#
# Why this exists:
#   The official quay.io/sharelatex/pandoc:3.9 image is private (401, can't pull).
#   clsi invokes pandoc generically (no custom templates/filters/reference-doc), so a
#   stock pandoc image works — it just needs three runtime essentials that clsi assumes:
#
#   1. No `pandoc` ENTRYPOINT — clsi runs Cmd ["pandoc", ...]; with the default
#      entrypoint that would become `pandoc pandoc ...`.
#   2. `zip` — the import conversion's second step runs `zip -r` to package the output.
#   3. Users matching how clsi runs the conversion container (User=$TEXLIVE_IMAGE_USER):
#        - `tex` at UID 1000 — dev / microservices default.
#        - `www-data` at UID 33 — Server Pro sandboxed *sibling* containers set
#          TEXLIVE_IMAGE_USER=www-data (see /etc/overleaf/env.sh). clsi (running as
#          www-data) creates the conversion dir owned by 33:33, so the container must run
#          as www-data(33) to write into it — otherwise pandoc fails with either
#          "unable to find user www-data" or "permission denied".
#      Alpine already ships a `www-data` group at GID 82, so we move it to GID 33 to
#      match the host/texlive image.
#
# Build (tag must match PANDOC_IMAGE in develop/dev.env):
#   docker build -t overleaf-pandoc:local develop/pandoc
#
# Note: pinned to `latest` (pandoc 3.10 at time of writing). Pin to a specific
# pandoc/core tag for fully reproducible builds.
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 theme={null}
docker build -t overleaf-pandoc:local develop/pandoc
```

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

***

### 疑難排解

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.