> 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/pt/configuracao/overleaf-toolkit/importacao-e-exportacao-com-o-pandoc.md). # Importação e exportação com o Pandoc ### Importação / exportação do Pandoc O Overleaf pode converter documentos de e para LaTeX usando [Pandoc](https://pandoc.org/). A conversão é executada dentro de um **contentor Docker em sandbox** gerido pelo `clsi` serviço, por isso a funcionalidade vem desativada por predefinição e tem de ser ativada com algumas variáveis de ambiente. #### O que faz | Direção | De → Para | Formatos | Onde | | ------------ | ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- | | **Importar** | documento → projeto LaTeX | `docx`, `markdown` | *Novo projeto → Importar* (carrega um `.docx` / `.md` e transforma-o num editável `.tex` projeto) | | **Exportar** | projeto LaTeX → documento | `docx`, `markdown`, `html` | *Menu → Descarregar / Exportar* (renderiza o projeto através do Pandoc) | *** ### Variáveis de ambiente Há **duas** variáveis que importam, e uma semelhante que faz **não**. 1\. `ENABLE_PANDOC_CONVERSIONS` — o interruptor principal ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * Tipo: booleano (`true` ativa-o; qualquer outra coisa desativa-o). * **Tem de ser definida em AMBOS os `web` e `clsi` serviços.** São processos separados com configuração separada: * `web` lê-a em `enablePandocConversions` (`services/web/config/settings.defaults.js`). Controla as rotas de importação, as rotas de exportação e a `ol-ExposedSettings.enablePandocConversions` bandeira que indica ao frontend se deve mostrar a interface de Importação/Exportação. * `clsi` lê-a em `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Controla os endpoints que executam o Pandoc. * Se estiver ativado em `web` mas não em `clsi` (ou vice-versa), a interface aparecerá, mas a conversão falhará — mantenha-os sincronizados. 2\. `PANDOC_IMAGE` — a imagem de contentor que o clsi executa para converter ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### Pré-requisitos Como as conversões são executadas como contentores Docker iniciados por `clsi`: 1. **`clsi` tem de ser executado em modo sandbox com acesso ao Docker.** Na stack de desenvolvimento `clsi` já tem `SANDBOXED_COMPILES=true` e o socket Docker do anfitrião (`/var/run/docker.sock`) montado. 2. **O `PANDOC_IMAGE` tem de estar presente** nesse anfitrião Docker (obtida por pull ou construída localmente) antes da primeira conversão. *** ### Configuração rápida A stack de desenvolvimento (`develop/dev.env`) já inclui: ```bash ENABLE_PANDOC_CONVERSIONS=true PANDOC_IMAGE=overleaf-pandoc:local ``` Como a imagem oficial é privada, construa a incluída **uma vez** antes de usar a funcionalidade: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Depois, (re)inicie a stack para que `clsi` e `web` detete as variáveis. *** ### Construindo a imagem do Pandoc Uma imagem padrão do Pandoc funciona porque o clsi invoca o Pandoc de forma genérica (sem modelos/filtros personalizados). Só precisa de três elementos essenciais em tempo de execução, todos tratados por `develop/pandoc/Dockerfile`: ```dockerfile # Imagem personalizada do Pandoc para conversões em sandbox do clsi # (importação/exportação: docx / markdown / html, via ENABLE_PANDOC_CONVERSIONS). # # Porque isto existe: # A imagem oficial quay.io/sharelatex/pandoc:3.9 é privada (401, não é possível fazer pull). # O clsi invoca o pandoc de forma genérica (sem modelos/filtros/reference-doc personalizados), por isso uma # imagem padrão do pandoc funciona — só precisa de três essenciais em tempo de execução que o clsi assume: # # 1. Sem ENTRYPOINT `pandoc` — o clsi executa Cmd ["pandoc", ...]; com o # entrypoint predefinido isso tornar-se-ia `pandoc pandoc ...`. # 2. `zip` — a segunda etapa da conversão de importação executa `zip -r` para empacotar o resultado. # 3. Utilizadores que correspondem à forma como o clsi executa o contentor de conversão (User=$TEXLIVE_IMAGE_USER): # - `tex` no UID 1000 — predefinição de dev / microservices. # - `www-data` no UID 33 — contentores *irmãos* em sandbox do Server Pro definem # TEXLIVE_IMAGE_USER=www-data (ver /etc/overleaf/env.sh). O clsi (a executar como # www-data) cria o diretório de conversão pertencente a 33:33, por isso o contentor tem de ser executado # como www-data(33) para escrever nele — caso contrário, o pandoc falha com # "unable to find user www-data" ou "permission denied". # O Alpine já inclui um grupo `www-data` no GID 82, por isso movemo-lo para o GID 33 para # corresponder ao anfitrião/imagem texlive. # # Construir (a tag tem de corresponder a PANDOC_IMAGE em develop/dev.env): # docker build -t overleaf-pandoc:local develop/pandoc # # Nota: fixado em `latest` (pandoc 3.10 no momento da redação). Fixe a um # tag específica de pandoc/core para builds totalmente reprodutíveis. 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 ``` Construa e atribua a tag para que a tag corresponda `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Para produção, fixe `pandoc/core` a uma versão específica em vez de `mais recente` para builds reprodutíveis, e defina `PANDOC_IMAGE` o caminho do seu registo. *** ### Resolução de problemas | Sintoma | Causa provável | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | Os botões de Importação/Exportação não aparecem | `ENABLE_PANDOC_CONVERSIONS` não `true` em **web** | | A interface aparece, mas a conversão falha com um erro do servidor | `ENABLE_PANDOC_CONVERSIONS` não definida em **clsi**, ou `PANDOC_IMAGE` em falta no anfitrião Docker | | `clsi` erro ao fazer pull da imagem (401) | `PANDOC_IMAGE` continua a apontar para o predefinido privado; construa/aponte para a sua própria imagem | | O contentor executa `pandoc pandoc …` / argumentos incorretos | A imagem tem um `pandoc` `ENTRYPOINT`; use `ENTRYPOINT []` | | O resultado da importação está vazio / a etapa zip falha | `zip` não está instalado na imagem | | Erros de permissão nos ficheiros convertidos | A imagem não tem `tex` utilizador no 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/pt/configuracao/overleaf-toolkit/importacao-e-exportacao-com-o-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.