> 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-cn/pei-zhi/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` 启用；其他任何值都会禁用它）。
* **必须同时在两个 `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 套接字（`/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 的沙箱化 *sibling* 容器设置
#          TEXLIVE_IMAGE_USER=www-data（参见 /etc/overleaf/env.sh）。clsi（以
#          www-data 运行）会创建所有者为 33:33 的转换目录，因此容器必须以
#          www-data(33) 身份运行才能写入——否则 pandoc 会失败，报错可能是
#          “无法找到用户 www-data”或“权限被拒绝”。
#      Alpine 默认自带 GID 82 的 `www-data` 组，因此我们把它改到 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` 设置为你的镜像仓库路径。

***

### 故障排除

| 症状                             | 可能原因                                                                                         |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| 导入/导出按钮未显示                     | `ENABLE_PANDOC_CONVERSIONS` 不要 `true` 中的 **web**                                             |
| 界面显示了，但转换因服务器错误失败              | `ENABLE_PANDOC_CONVERSIONS` 未在……上设置 **clsi**运行你的 Overleaf 实例，或 `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-cn/pei-zhi/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.