> ## 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 套接字（`/var/run/docker.sock`）。
2. **在首次转换之前，`PANDOC_IMAGE` 必须已存在于**该 Docker 主机上（拉取或在本地构建）。

***

### 快速设置

开发环境（`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` 设置为你的镜像仓库路径。

***

### 故障排除

| 现象 | 可能原因 |
| - | - |
| 导入/导出按钮未显示 | **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.