> 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/ru/konfiguraciya/overleaf-toolkit/pandoc-import-and-export.md). # Импорт и экспорт Pandoc ### Импорт / экспорт Pandoc Overleaf может преобразовывать документы в LaTeX и обратно с помощью [Pandoc](https://pandoc.org/). Преобразование выполняется внутри **изолированного контейнера Docker** управляемого `clsi` сервисом, поэтому функция по умолчанию отключена и должна быть включена с помощью нескольких переменных окружения. #### Что это делает | Направление | Из → В | Форматы | Где | | ----------- | ----------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | **Импорт** | документ → проект LaTeX | `docx`, `markdown` | *Новый проект → Импорт* (загружает `.docx` / `.md` и преобразует его в редактируемый `.tex` проект) | | **Экспорт** | проект LaTeX → документ | `docx`, `markdown`, `html` | *Меню → Скачать / Экспорт* (рендерит проект через Pandoc) | *** ### Переменные среды Есть **две** переменные, которые важны, и одна похожая, которая не **не**. 1\. `ENABLE_PANDOC_CONVERSIONS` — главный переключатель ```bash ENABLE_PANDOC_CONVERSIONS=true ``` * Тип: логический (`true` включает его; всё остальное отключает его). * **Должно быть задано в ОБОИХ `web` и `clsi` сервисах.** Это отдельные процессы с отдельной конфигурацией: * `web` считывает его в `enablePandocConversions` (`services/web/config/settings.defaults.js`). Оно управляет маршрутами импорта, маршрутами экспорта и `ol-ExposedSettings.enablePandocConversions` флагом, который сообщает фронтенду, показывать ли интерфейс Импорт/Экспорт. * `clsi` считывает его в `enablePandocConversions` (`services/clsi/config/settings.defaults.cjs`). Оно управляет конечными точками, которые запускают Pandoc. * Если оно включено в `web` но не в `clsi` (или наоборот), интерфейс будет отображаться, но преобразование завершится сбоем — держите их в синхронизации. 2\. `PANDOC_IMAGE` — образ контейнера, который clsi запускает для преобразования ```bash PANDOC_IMAGE=your-repo/pandoc:3.9 ``` ### Предварительные требования Поскольку преобразования выполняются в виде контейнеров Docker, запускаемых `clsi`: 1. **`clsi` должен работать в изолированном режиме с доступом к Docker.** В dev-стеке `clsi` уже имеет `SANDBOXED_COMPILES=true` и сокет Docker на хосте (`/var/run/docker.sock`) смонтирован. 2. **Параметр `PANDOC_IMAGE` должен присутствовать** на этом Docker-хосте (загружен или собран локально) до первого преобразования. *** ### Быстрая настройка dev-стек (`develop/dev.env`) уже поставляется с: ```bash ENABLE_PANDOC_CONVERSIONS=true PANDOC_IMAGE=overleaf-pandoc:local ``` Поскольку официальный образ является приватным, соберите встроенный **один раз** перед использованием функции: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Затем (пере)запустите стек, чтобы `clsi` и `web` подхватить переменные. *** ### Сборка образа Pandoc Стандартный образ Pandoc подходит, потому что clsi вызывает Pandoc в общем виде (без пользовательских шаблонов/фильтров). Ему нужны только три основных компонента во время выполнения, и все они обеспечиваются `develop/pandoc/Dockerfile`: ```dockerfile # Пользовательский образ Pandoc для изолированных преобразований clsi # (импорт/экспорт: docx / markdown / html, через ENABLE_PANDOC_CONVERSIONS). # # Зачем это нужно: # Официальный образ quay.io/sharelatex/pandoc:3.9 приватный (401, не удаётся загрузить). # clsi вызывает pandoc в общем виде (без пользовательских шаблонов/фильтров/reference-doc), поэтому # стандартный образ pandoc подходит — ему нужны лишь три базовых компонента, которые clsi предполагает: # # 1. Никакого `pandoc` ENTRYPOINT — clsi запускает Cmd ["pandoc", ...]; с обычным # entrypoint это превратилось бы в `pandoc pandoc ...`. # 2. `zip` — на втором шаге преобразования импорта выполняется `zip -r` для упаковки результата. # 3. Пользователи должны соответствовать тому, как clsi запускает контейнер преобразования (User=$TEXLIVE_IMAGE_USER): # - `tex` с UID 1000 — значение по умолчанию для dev / микросервисов. # - `www-data` с UID 33 — изолированные *соседние* контейнеры Server Pro задают # TEXLIVE_IMAGE_USER=www-data (см. /etc/overleaf/env.sh). clsi (работая как # www-data) создаёт каталог преобразования, принадлежащий 33:33, поэтому контейнер должен работать # как www-data(33), чтобы записывать в него — иначе pandoc завершится ошибкой либо # "не удается найти пользователя www-data", либо "permission denied". # В Alpine уже есть группа `www-data` с GID 82, поэтому мы переносим её на GID 33, чтобы # соответствовать хосту/образу texlive. # # Сборка (тег должен совпадать с PANDOC_IMAGE в develop/dev.env): # docker build -t overleaf-pandoc:local develop/pandoc # # Примечание: закреплено за `latest` (pandoc 3.10 на момент написания). Привяжите к конкретному # тегу pandoc/core для полностью воспроизводимых сборок. 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 ``` Соберите и пометьте тегом так, чтобы тег совпадал `PANDOC_IMAGE`: ```bash docker build -t overleaf-pandoc:local develop/pandoc ``` Для production закрепите `pandoc/core` за конкретной версией вместо `latest` для воспроизводимых сборок, и задайте `PANDOC_IMAGE` путь в вашем реестре. *** ### Устранение неполадок | Симптом | Вероятная причина | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Кнопки Импорт/Экспорт не отображаются | `ENABLE_PANDOC_CONVERSIONS` не `true` на **web** | | Интерфейс отображается, но преобразование завершается ошибкой сервера | `ENABLE_PANDOC_CONVERSIONS` не задано в **clsi**, или `PANDOC_IMAGE` отсутствует на Docker-хосте | | `clsi` ошибка при загрузке образа (401) | `PANDOC_IMAGE` по-прежнему указывает на приватный образ по умолчанию; соберите/укажите свой собственный образ | | Контейнер запускается `pandoc pandoc …` / неверные аргументы | В образе есть `pandoc` `ENTRYPOINT`; используйте `ENTRYPOINT []` | | Результат импорта пуст / шаг zip завершается сбоем | `zip` не установлен в образе | | Ошибки прав доступа к преобразованным файлам | В образе нет `tex` пользователя с 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/ru/konfiguraciya/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.