> ## 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.

# Importazione ed esportazione con Pandoc

### Importazione / esportazione con Pandoc

Overleaf può convertire documenti da e verso LaTeX usando [Pandoc](https://pandoc.org/). La conversione viene eseguita all'interno di un **container Docker in sandbox** gestito dal servizio `clsi`, per cui la funzionalità è disattivata per impostazione predefinita e deve essere attivata con un paio di variabili d'ambiente.

#### Cosa fa

| Direzione | Da → A | Formati | Dove |
| - | - | - | - |
| **Importazione** | documento → progetto LaTeX | `docx`, `markdown` | *New Project → Import* (carica un file `.docx` / `.md` e lo trasforma in un progetto `.tex` modificabile) |
| **Esportazione** | progetto LaTeX → documento | `docx`, `markdown`, `html` | *Menu → Download / Export* (esegue il rendering del progetto tramite Pandoc) |

***

### Variabili d'ambiente

Le variabili rilevanti sono **due**, più una dal nome simile che **non** lo è.

1\. `ENABLE_PANDOC_CONVERSIONS` — l'interruttore principale

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

* Tipo: booleano (`true` la abilita; qualsiasi altro valore la disabilita).
* <strong>Deve essere impostata su ENTRAMBI i servizi `web` e `clsi`.</strong> Sono processi separati con configurazioni separate:
  * `web` la legge in `enablePandocConversions` (`services/web/config/settings.defaults.js`). Controlla le route di importazione, le route di esportazione e il flag `ol-ExposedSettings.enablePandocConversions` che indica al frontend se mostrare l'interfaccia di importazione/esportazione.
  * `clsi` la legge in `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Controlla gli endpoint che eseguono Pandoc.
* Se è abilitata su `web` ma non su `clsi` (o viceversa), l'interfaccia comparirà ma la conversione non andrà a buon fine: mantienile sincronizzate.

2\. `PANDOC_IMAGE` — l'immagine del container che clsi esegue per la conversione

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

### Prerequisiti

Poiché le conversioni vengono eseguite come container Docker avviati da `clsi`:

1. <strong>`clsi` deve essere eseguito in modalità sandbox con accesso a Docker.</strong> Nello stack di sviluppo `clsi` ha già `SANDBOXED_COMPILES=true` e il socket Docker dell'host (`/var/run/docker.sock`) montato.
2. **L'immagine `PANDOC_IMAGE` deve essere presente** su quell'host Docker (scaricata o costruita in locale) prima della prima conversione.

***

### Configurazione rapida

Lo stack di sviluppo (`develop/dev.env`) include già:

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

Poiché l'immagine ufficiale è privata, costruisci **una volta** quella inclusa prima di usare la funzionalità:

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

Quindi (ri)avvia lo stack affinché `clsi` e `web` acquisiscano le variabili.

***

### Costruire l'immagine Pandoc

Un'immagine Pandoc standard funziona perché clsi invoca Pandoc in modo generico (senza template/filtri personalizzati). Servono solo tre requisiti di runtime essenziali, tutti gestiti da `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
```

Costruiscila e assegnale un tag che corrisponda a `PANDOC_IMAGE`:

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

In produzione, fissa `pandoc/core` a una versione specifica anziché `latest` per avere build riproducibili, e imposta `PANDOC_IMAGE` sul percorso del tuo registry.

***

### Risoluzione dei problemi

| Sintomo | Causa probabile |
| - | - |
| I pulsanti di importazione/esportazione non compaiono | `ENABLE_PANDOC_CONVERSIONS` non è `true` su **web** |
| L'interfaccia compare ma la conversione fallisce con un errore del server | `ENABLE_PANDOC_CONVERSIONS` non impostata su **clsi**, oppure `PANDOC_IMAGE` assente sull'host Docker |
| Errore di `clsi` durante il pull dell'immagine (401) | `PANDOC_IMAGE` punta ancora all'immagine privata predefinita; costruisci o indica la tua immagine |
| Il container esegue `pandoc pandoc …` / argomenti errati | L'immagine ha un `ENTRYPOINT` `pandoc`; usa `ENTRYPOINT []` |
| L'output dell'importazione è vuoto / il passaggio zip fallisce | `zip` non è installato nell'immagine |
| Errori di permessi sui file convertiti | L'immagine non ha un utente `tex` con UID 1000 |


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