> 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/it/configurazione/overleaf-toolkit/pandoc-import-and-export.md). # Importazione ed esportazione con Pandoc ### Importazione / esportazione Pandoc Overleaf può convertire documenti da e verso LaTeX usando [Pandoc](https://pandoc.org/). La conversione viene eseguita all'interno di un **container Docker isolato** gestito dal `clsi` servizio, quindi la funzione è disattivata per impostazione predefinita e va attivata con un paio di variabili d'ambiente. #### Cosa fa | Direzione | Da → A | Formati | Dove | | ---------------- | -------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- | | **Importazione** | documento → progetto LaTeX | `docx`, `markdown` | *Nuovo progetto → Importa* (carica un `.docx` / `.md` e lo trasforma in un `.tex` progetto) | | **Esportazione** | progetto LaTeX → documento | `docx`, `markdown`, `html` | *Menu → Scarica / Esporta* (renderizza il progetto tramite Pandoc) | *** ### Variabili d'ambiente Ci sono **due** variabili importanti, e una simile che fa **non**. 1\. `ENABLE_PANDOC_CONVERSIONS` — l'interruttore principale ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * Tipo: booleano (`true` lo abilita; qualsiasi altra cosa lo disabilita). * **Deve essere impostato su ENTRAMBI i `web` e `clsi` servizi.** Sono processi separati con configurazioni separate: * `web` lo 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 Importa/Esporta. * `clsi` lo legge in `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Controlla gli endpoint che eseguono Pandoc. * Se è abilitato su `web` ma non su `clsi` (o viceversa), l'interfaccia apparirà ma la conversione fallirà — mantienili sincronizzati. 2\. `PANDOC_IMAGE` — l'immagine del container che clsi esegue per convertire ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### Prerequisiti Poiché le conversioni vengono eseguite come container Docker avviati da `clsi`: 1. **`clsi` deve essere eseguito in modalità isolata con accesso a Docker.** Nello stack di sviluppo `clsi` ha già `SANDBOXED_COMPILES=true` e il socket Docker dell'host (`/var/run/docker.sock`) montato. 2. **Il `PANDOC_IMAGE` deve essere presente** su quell'host Docker (scaricata o compilata localmente) prima della prima conversione. *** ### Configurazione rapida Lo stack di sviluppo (`develop/dev.env`) include già: ```bash ENABLE_PANDOC_CONVERSIONS=true PANDOC_IMAGE=overleaf-pandoc:local ``` Poiché l'immagine ufficiale è privata, compila quella inclusa **una volta** prima di usare la funzione: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Quindi (ri)avvia lo stack così `clsi` e `web` rilevano le variabili. *** ### Compilazione dell'immagine Pandoc Un'immagine Pandoc standard funziona perché clsi invoca Pandoc in modo generico (senza template/filtro personalizzati). Ha bisogno solo di tre requisiti di runtime, tutti gestiti da `develop/pandoc/Dockerfile`: ```dockerfile # Immagine Pandoc personalizzata per le conversioni isolate di clsi # (importazione/esportazione: docx / markdown / html, tramite ENABLE_PANDOC_CONVERSIONS). # # Perché esiste: # L'immagine ufficiale quay.io/sharelatex/pandoc:3.9 è privata (401, impossibile scaricarla). # clsi invoca pandoc in modo generico (senza template/filtro/reference-doc personalizzati), quindi un # immagine pandoc standard funziona — ha solo bisogno di tre requisiti di runtime che clsi presume: # # 1. Nessun ENTRYPOINT `pandoc` — clsi esegue Cmd ["pandoc", ...]; con l'entrypoint predefinito # questo diventerebbe `pandoc pandoc ...`. # 2. `zip` — il secondo passaggio della conversione di importazione esegue `zip -r` per impacchettare l'output. # 3. Utenti corrispondenti a come clsi esegue il container di conversione (User=$TEXLIVE_IMAGE_USER): # - `tex` con UID 1000 — predefinito per dev / microservizi. # - `www-data` con UID 33 — i container *fratelli* isolati di Server Pro impostano # TEXLIVE_IMAGE_USER=www-data (vedi /etc/overleaf/env.sh). clsi (in esecuzione come # www-data) crea la directory di conversione di proprietà di 33:33, quindi il container deve essere eseguito # come www-data(33) per scriverci — altrimenti pandoc fallisce con # "unable to find user www-data" oppure "permission denied". # Alpine include già un gruppo `www-data` con GID 82, quindi lo spostiamo al GID 33 per # corrispondere all'host/immagine texlive. # # Compila (il tag deve corrispondere a PANDOC_IMAGE in develop/dev.env): # docker build -t overleaf-pandoc:local develop/pandoc # # Nota: bloccato su `latest` (pandoc 3.10 al momento della stesura). Bloccalo a un tag # pandoc/core specifico per build completamente riproducibili. 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 ``` Compilalo e taggalo in modo che il tag corrisponda `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` In produzione, blocca `pandoc/core` a una versione specifica invece di `latest` per build riproducibili, e imposta `PANDOC_IMAGE` al percorso del tuo registro. *** ### Risoluzione dei problemi | Sintomo | Probabile causa | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | I pulsanti Importa/Esporta non compaiono | `ENABLE_PANDOC_CONVERSIONS` non `true` su **web** | | L'interfaccia appare ma la conversione fallisce con un errore del server | `ENABLE_PANDOC_CONVERSIONS` non impostato su **clsi**, oppure `PANDOC_IMAGE` mancante sull'host Docker | | `clsi` errore durante il pull dell'immagine (401) | `PANDOC_IMAGE` punta ancora al valore predefinito privato; compila/indirizza verso la tua immagine | | Il container esegue `pandoc pandoc …` / argomenti errati | L'immagine ha un `pandoc` `ENTRYPOINT`; 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 alcun `tex` utente con 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/it/configurazione/overleaf-toolkit/pandoc-import-and-export.md?ask=&goal= ``` `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.