Importación y exportación con Pandoc

​

Importación / exportación con Pandoc

Overleaf puede convertir documentos desde y hacia LaTeX mediante Pandoc. La conversión se ejecuta dentro de un contenedor Docker en sandbox gestionado por el servicio clsi, por lo que la función está desactivada de forma predeterminada y debe activarse con un par de variables de entorno.

​

Qué hace

Dirección	De → A	Formatos	Dónde
Importación	documento → proyecto LaTeX	docx, markdown	Nuevo proyecto → Importar (sube un .docx / .md y lo convierte en un proyecto .tex editable)
Exportación	proyecto LaTeX → documento	docx, markdown, html	Menú → Descargar / Exportar (procesa el proyecto a través de Pandoc)

---

​

Variables de entorno

Hay dos variables que importan, y una de nombre parecido que no.

1. ENABLE_PANDOC_CONVERSIONS: el interruptor principal

ENABLE_PANDOC_CONVERSIONS=true

• Tipo: booleano (true lo habilita; cualquier otro valor lo deshabilita).
• Debe establecerse en AMBOS servicios, web y clsi. Son procesos separados con configuración separada:
  • web la lee en enablePandocConversions (services/web/config/settings.defaults.js). Controla las rutas de importación, las rutas de exportación y el indicador ol-ExposedSettings.enablePandocConversions que indica al frontend si debe mostrar la interfaz de importación/exportación.
  • clsi la lee en enablePandocConversions (services/clsi/config/settings.defaults.cjs). Controla los endpoints que ejecutan Pandoc.
• Si está habilitada en web pero no en clsi (o viceversa), la interfaz aparecerá pero la conversión fallará: mantenlas sincronizadas.

2. PANDOC_IMAGE: la imagen de contenedor que clsi ejecuta para convertir

PANDOC_IMAGE=your-repo/pandoc:3.9

​

Requisitos previos

Como las conversiones se ejecutan como contenedores Docker lanzados por clsi:

1. clsi debe ejecutarse en modo sandbox con acceso a Docker. En el stack de desarrollo, clsi ya tiene SANDBOXED_COMPILES=true y el socket de Docker del host (/var/run/docker.sock) montado.
2. La PANDOC_IMAGE debe estar presente en ese host de Docker (descargada o compilada localmente) antes de la primera conversión.

---

​

Configuración rápida

El stack de desarrollo (develop/dev.env) ya incluye:

ENABLE_PANDOC_CONVERSIONS=true
PANDOC_IMAGE=overleaf-pandoc:local

Como la imagen oficial es privada, compila una vez la imagen incluida antes de usar la función:

docker build -t overleaf-pandoc:local develop/pandoc

A continuación, (re)inicia el stack para que clsi y web lean las variables.

---

​

Compilar la imagen de Pandoc

Una imagen estándar de Pandoc funciona porque clsi invoca Pandoc de forma genérica (sin plantillas ni filtros personalizados). Solo necesita tres elementos esenciales en tiempo de ejecución, todos gestionados por develop/pandoc/Dockerfile:

# 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

Compílala y etiquétala de modo que la etiqueta coincida con PANDOC_IMAGE:

docker build -t overleaf-pandoc:local develop/pandoc

En producción, fija pandoc/core a una versión concreta en lugar de latest para obtener compilaciones reproducibles, y establece PANDOC_IMAGE con la ruta de tu registro.

---

​

Solución de problemas

Síntoma	Causa probable
No aparecen los botones de importar/exportar	ENABLE_PANDOC_CONVERSIONS no es true en web
La interfaz aparece pero la conversión falla con un error del servidor	ENABLE_PANDOC_CONVERSIONS no está establecida en clsi, o falta PANDOC_IMAGE en el host de Docker
Error de clsi al descargar la imagen (401)	PANDOC_IMAGE sigue apuntando al valor predeterminado privado; compila/apunta a tu propia imagen
El contenedor ejecuta pandoc pandoc … / argumentos incorrectos	La imagen tiene un ENTRYPOINT pandoc; usa ENTRYPOINT []
La salida de la importación está vacía / falla el paso zip	zip no está instalado en la imagen
Errores de permisos en los archivos convertidos	La imagen no tiene un usuario tex con UID 1000