> ## 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` | *New Project → Import*（`.docx` / `.md` をアップロードし、編集可能な `.tex` プロジェクトに変換） |
| **エクスポート** | LaTeX プロジェクト → ドキュメント | `docx`、`markdown`、`html` | *Menu → Download / Export*（Pandoc を通してプロジェクトを出力） |

***

### 環境変数

重要な変数は **2 つ**あり、似ているが関係**ない**ものが 1 つあります。

1\. `ENABLE_PANDOC_CONVERSIONS` — マスタースイッチ

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

* 型：boolean（`true` で有効、それ以外の値では無効）。
* <strong>`web` と `clsi` の両方のサービスで設定する必要があります。</strong> これらは個別の設定を持つ別々のプロセスです。
  * `web` はこれを `enablePandocConversions`（`services/web/config/settings.defaults.js`）に読み込みます。これにより、インポートルート、エクスポートルート、およびフロントエンドにインポート/エクスポート UI を表示するかどうかを伝える `ol-ExposedSettings.enablePandocConversions` フラグが制御されます。
  * `clsi` はこれを `enablePandocConversions`（`services/clsi/config/settings.defaults.cjs`）に読み込みます。これにより、Pandoc を実行するエンドポイントが制御されます。
* `web` で有効にして `clsi` で有効にしない場合（またはその逆の場合）、UI は表示されますが変換は失敗します。両者の設定を一致させてください。

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. 最初の変換の前に、その Docker ホスト上に **`PANDOC_IMAGE` が存在している必要があります**（pull するか、ローカルでビルドします）。

***

### クイックセットアップ

開発スタック（`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 イメージで動作します。必要なのは 3 つの実行時要件だけで、すべて `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` になっていない |
| UI は表示されるが、変換がサーバーエラーで失敗する | **clsi** で `ENABLE_PANDOC_CONVERSIONS` が設定されていない、または Docker ホストに `PANDOC_IMAGE` が存在しない |
| イメージの pull 時に `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.