> 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/ja/she-ding/overleaf-toolkit/pandoc-import-and-export.md).

# Pandoc のインポートとエクスポート

### Pandoc インポート / エクスポート

Overleaf は、以下を使って LaTeX 形式への変換および LaTeX 形式からの変換ができます [Pandoc](https://pandoc.org/)。変換は、 **サンドボックス化された Docker コンテナ** によって管理される `clsi` サービス内で実行されるため、この機能はデフォルトではオフで、いくつかの環境変数で有効にする必要があります。

#### できること

| 方向         | From → To         | 形式                         | 場所                                                                       |
| ---------- | ----------------- | -------------------------- | ------------------------------------------------------------------------ |
| **インポート**  | 文書 → LaTeX プロジェクト | `docx`, `markdown`         | *新規プロジェクト → インポート* （ `.docx` / `.md` をアップロードし、編集可能な `.tex` プロジェクトに変換します） |
| **エクスポート** | LaTeX プロジェクト → 文書 | `docx`, `markdown`, `html` | *メニュー → ダウンロード / エクスポート* （Pandoc を通してプロジェクトをレンダリングします）                   |

***

### 環境変数

重要なのは **2つ** の変数で、ほかに見た目が似ているだけで役に立たないものが1つあります **しないでください**.

1\. `ENABLE_PANDOC_CONVERSIONS` — メインスイッチ

```bash
ENABLE_PANDOC_CONVERSIONS=true
```

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

2\. `PANDOC_IMAGE` — clsi が変換に使うコンテナイメージ

```bash
PANDOC_IMAGE=your-repo/pandoc:3.9
```

### 前提条件

変換は、 `clsi`:

1. **`clsi` によって起動される Docker コンテナとして実行されるため、** 開発用スタックでは `clsi` すでに `SANDBOXED_COMPILES=true` とホストの Docker ソケット（`/var/run/docker.sock`）がマウントされています。
2. **次の `PANDOC_IMAGE` が存在している必要があります** 最初の変換の前に、その Docker ホスト上に（pull 済みまたはローカルでビルド済みの状態で）

***

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

開発用スタック（`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 を汎用的に呼び出すためです（独自のテンプレート/フィルタは使いません）。必要なのは実行時の基本要件3つだけで、すべて `develop/pandoc/Dockerfile`:

```dockerfile
# clsi のサンドボックス化された変換用のカスタム Pandoc イメージ
# （インポート/エクスポート: docx / markdown / html、ENABLE_PANDOC_CONVERSIONS 経由）。
#
# これが存在する理由:
#   公式の quay.io/sharelatex/pandoc:3.9 イメージは非公開です（401 のため pull できません）。
#   clsi は pandoc を汎用的に呼び出すため（独自の templates/filters/reference-doc はなし）、
#   標準の pandoc イメージで動作します。必要なのは、clsi が想定する実行時の基本要件3つだけです:
#
#   1. `pandoc` の ENTRYPOINT がないこと — clsi は Cmd ["pandoc", ...] を実行します。デフォルトの
#      entrypoint のままだと `pandoc pandoc ...` になってしまいます。
#   2. `zip` — インポート変換の第2段階では、出力をまとめるために `zip -r` を実行します。
#   3. clsi が変換コンテナを実行する方法に合わせたユーザー（User=$TEXLIVE_IMAGE_USER）:
#        - UID 1000 の `tex` — 開発環境 / microservices のデフォルト。
#        - 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 は
#          "unable to find user www-data" または "permission denied" で失敗します。
#      Alpine にはすでに GID 82 の `www-data` グループがあるため、ホスト/texlive イメージに
#      合わせるために GID 33 に移動します。
#
# ビルド（タグは 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**                            |
| UI は表示されるが、変換がサーバーエラーで失敗する         | `ENABLE_PANDOC_CONVERSIONS` で設定されていない **clsi**、または `PANDOC_IMAGE` Docker ホスト上にない |
| `clsi` イメージの pull 失敗（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/ja/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.