> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/it/configurazione/overleaf-toolkit/importazione-ed-esportazione-pandoc.md). # Importazione ed esportazione 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 **contenitore Docker isolato** gestito dal `clsi` servizio, quindi 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` | *Nuovo progetto → Importa* (carica un `.docx` / `.md` e lo trasforma in un `.tex` modificabile) | | **Esportazione** | progetto LaTeX → documento | `docx`, `markdown`, `html` | *Menu → Scarica / Esporta* (esegue il rendering del progetto tramite Pandoc) | *** ### variabili d'ambiente Ci sono **due** variabili che contano, e una simile che non lo 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 `ol-ExposedSettings.enablePandocConversions` flag 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 contenitore che clsi esegue per convertire ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### Prerequisiti Poiché le conversioni vengono eseguite come contenitori Docker avviati da `clsi`: 1. **`clsi` deve essere eseguito in modalità sandbox 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 funzionalità: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Poi (ri)avvia lo stack in modo che `clsi` e `web` raccolga le variabili. *** ### Compilazione dell'immagine Pandoc Un'immagine Pandoc standard funziona perché clsi richiama Pandoc in modo generico (nessun template/filtro personalizzato). Ha bisogno solo di tre elementi essenziali a runtime, tutti gestiti da `develop/pandoc/Dockerfile`: ```dockerfile # Immagine Pandoc personalizzata per le conversioni in sandbox 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 richiama pandoc in modo generico (nessun template/filtro/reference-doc personalizzato), quindi una # immagine pandoc standard funziona: servono solo tre elementi essenziali a runtime che clsi presuppone: # # 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 contenitore di conversione (User=$TEXLIVE_IMAGE_USER): # - `tex` con UID 1000 — predefinito per dev / microservizi. # - `www-data` con UID 33 — i contenitori *fratelli* sandboxed 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 posseduta da 33:33, quindi il contenitore deve essere eseguito # come www-data(33) per scriverci dentro — altrimenti pandoc fallisce con # "impossibile trovare l'utente www-data" oppure "permission denied". # Alpine include già un gruppo `www-data` con GID 82, quindi lo spostiamo a GID 33 per # corrispondere all'host/immagine texlive. # # Build (il tag deve corrispondere a PANDOC_IMAGE in develop/dev.env): # docker build -t overleaf-pandoc:local develop/pandoc # # Nota: fissato a `latest` (pandoc 3.10 al momento della scrittura). Blocca a una # tag specifico di pandoc/core 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 ``` Compilala e assegnale un tag in modo che il tag corrisponda `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Per la produzione, blocca `pandoc/core` a una versione specifica invece di `latest` per build riproducibili, e imposta `PANDOC_IMAGE` al percorso del tuo registry. *** ### 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 nel pull dell'immagine (401) | `PANDOC_IMAGE` punta ancora al valore predefinito privato; compila/punta alla tua immagine | | Il contenitore 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 autorizzazione sui file convertiti | L'immagine non ha `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://overleaf-pro.ayaka.space/on-premises/it/configurazione/overleaf-toolkit/importazione-ed-esportazione-pandoc.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.