> ## 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-Import und -Export

### Pandoc-Import / -Export

Overleaf kann Dokumente mithilfe von [Pandoc](https://pandoc.org/) nach LaTeX und aus LaTeX konvertieren. Die Konvertierung läuft in einem **Docker-Container in einer Sandbox**, der vom Dienst `clsi` verwaltet wird. Daher ist die Funktion standardmäßig deaktiviert und muss über einige Umgebungsvariablen eingeschaltet werden.

#### Was die Funktion leistet

| Richtung | Von → Nach | Formate | Wo |
| - | - | - | - |
| **Import** | Dokument → LaTeX-Projekt | `docx`, `markdown` | *Neues Projekt → Importieren* (lädt eine `.docx`- / `.md`-Datei hoch und wandelt sie in ein bearbeitbares `.tex`-Projekt um) |
| **Export** | LaTeX-Projekt → Dokument | `docx`, `markdown`, `html` | *Menü → Herunterladen / Exportieren* (rendert das Projekt über Pandoc) |

***

### Umgebungsvariablen

Es gibt **zwei** relevante Variablen und eine ähnlich aussehende, die **nicht** relevant ist.

1\. `ENABLE_PANDOC_CONVERSIONS` – der Hauptschalter

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

* Typ: boolesch (`true` aktiviert die Funktion; jeder andere Wert deaktiviert sie).
* <strong>Muss sowohl für den Dienst `web` ALS AUCH für `clsi` gesetzt werden.</strong> Es handelt sich um separate Prozesse mit separater Konfiguration:
  * `web` liest die Variable in `enablePandocConversions` ein (`services/web/config/settings.defaults.js`). Sie steuert die Import-Routen, die Export-Routen sowie das Flag `ol-ExposedSettings.enablePandocConversions`, das dem Frontend mitteilt, ob die Import-/Export-Oberfläche angezeigt werden soll.
  * `clsi` liest die Variable in `enablePandocConversions` ein (`services/clsi/config/settings.defaults.cjs`). Sie steuert die Endpunkte, die Pandoc ausführen.
* Ist die Variable für `web`, aber nicht für `clsi` aktiviert (oder umgekehrt), erscheint zwar die Oberfläche, aber die Konvertierung schlägt fehl – halten Sie beide synchron.

2\. `PANDOC_IMAGE` – das Container-Image, das clsi für die Konvertierung ausführt

```bash theme={null}
PANDOC_IMAGE=your-repo/pandoc:3.9
```

### Voraussetzungen

Da die Konvertierungen als Docker-Container laufen, die von `clsi` gestartet werden:

1. <strong>`clsi` muss im Sandbox-Modus mit Docker-Zugriff laufen.</strong> Im Entwicklungs-Stack ist für `clsi` bereits `SANDBOXED_COMPILES=true` gesetzt und der Docker-Socket des Hosts (`/var/run/docker.sock`) eingebunden.
2. **Das `PANDOC_IMAGE` muss** vor der ersten Konvertierung auf diesem Docker-Host **vorhanden sein** (heruntergeladen oder lokal gebaut).

***

### Schnelleinrichtung

Der Entwicklungs-Stack (`develop/dev.env`) enthält bereits:

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

Da das offizielle Image privat ist, bauen Sie das mitgelieferte Image **einmalig**, bevor Sie die Funktion nutzen:

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

Starten Sie dann den Stack (neu), damit `clsi` und `web` die Variablen übernehmen.

***

### Das Pandoc-Image bauen

Ein Standard-Pandoc-Image funktioniert, da clsi Pandoc generisch aufruft (ohne benutzerdefinierte Vorlagen/Filter). Es benötigt lediglich drei grundlegende Laufzeitvoraussetzungen, die alle von `develop/pandoc/Dockerfile` abgedeckt werden:

```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
```

Bauen und taggen Sie es so, dass der Tag mit `PANDOC_IMAGE` übereinstimmt:

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

Für die Produktion sollten Sie `pandoc/core` für reproduzierbare Builds auf eine bestimmte Version statt auf `latest` festlegen und `PANDOC_IMAGE` auf den Pfad in Ihrer Registry setzen.

***

### Fehlerbehebung

| Symptom | Wahrscheinliche Ursache |
| - | - |
| Import-/Export-Schaltflächen werden nicht angezeigt | `ENABLE_PANDOC_CONVERSIONS` ist für **web** nicht auf `true` gesetzt |
| Oberfläche erscheint, aber Konvertierung schlägt mit Serverfehler fehl | `ENABLE_PANDOC_CONVERSIONS` ist für **clsi** nicht gesetzt oder `PANDOC_IMAGE` fehlt auf dem Docker-Host |
| `clsi`-Fehler beim Abrufen des Images (401) | `PANDOC_IMAGE` verweist noch auf den privaten Standardwert; bauen Sie ein eigenes Image bzw. verweisen Sie darauf |
| Container führt `pandoc pandoc …` aus / falsche Argumente | Das Image hat einen `pandoc`-`ENTRYPOINT`; verwenden Sie `ENTRYPOINT []` |
| Import-Ausgabe ist leer / zip-Schritt schlägt fehl | `zip` ist im Image nicht installiert |
| Berechtigungsfehler bei konvertierten Dateien | Das Image hat keinen Benutzer `tex` mit UID 1000 |


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