> 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/pt/configuracao/overleaf-toolkit/pandoc-import-and-export.md). # Importação e exportação do Pandoc ### Importação / Exportação com Pandoc O Overleaf pode converter documentos de e para LaTeX usando [Pandoc](https://pandoc.org/). A conversão é executada dentro de um **contentor Docker isolado** gerido pelo `clsi` serviço, pelo que a funcionalidade está 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 converte-o num editável `.tex` projeto) | | **Exportar** | projeto LaTeX → documento | `docx`, `markdown`, `html` | *Menu → Transferir / Exportar* (renderiza o projeto através do Pandoc) | *** ### Variáveis de ambiente Existem **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ê-o em `enablePandocConversions` (`services/web/config/settings.defaults.js`). Controla as rotas de importação, as rotas de exportação e a `ol-ExposedSettings.enablePandocConversions` sinalizador que diz ao frontend se deve mostrar a interface de Importação/Exportação. * `clsi` lê-o 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 pelo `clsi`: 1. **`clsi` tem de correr em modo sandbox com acesso ao Docker.** Na pilha 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 pilha 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, reinicie a pilha para que `clsi` e `web` as variáveis sejam aplicadas. *** ### Construindo a imagem do Pandoc Uma imagem standard 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 Pandoc personalizada 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 pode ser obtida por pull). # o clsi invoca o pandoc de forma genérica (sem templates/filtros/reference-doc personalizados), por isso uma # imagem standard do pandoc funciona — só precisa de três elementos essenciais em tempo de execução que o clsi pressupõe: # # 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` com UID 1000 — predefinição de dev / microservices. # - `www-data` com UID 33 — os contentores *irmãos* em sandbox do Server Pro definem # TEXLIVE_IMAGE_USER=www-data (ver /etc/overleaf/env.sh). o clsi (a correr como # www-data) cria o diretório de conversão propriedade de 33:33, por isso o contentor tem de correr # 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` com GID 82, por isso movemo-lo para GID 33 para # corresponder à imagem do anfitrião/texlive. # # Construir (a tag tem de corresponder ao 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 numa # 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-o e marque-o com a tag para que a tag corresponda `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Em produção, fixe `pandoc/core` a uma versão específica em vez de `latest` para builds reproduzíveis, e defina `PANDOC_IMAGE` para 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 está definida em **clsi**, ou `PANDOC_IMAGE` em falta no anfitrião Docker | | `clsi` erro ao obter a imagem por pull (401) | `PANDOC_IMAGE` ainda aponta para a predefinição privada; construa/aponte para a sua própria imagem | | O contentor executa `pandoc pandoc …` / argumentos errados | 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://ayakaleaf-pro.ayaka.space/on-premises/pt/configuracao/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.