> 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/uk/konfiguraciya/overleaf-toolkit/import-i-eksport-pandoc.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.** У розробницькому стеку `clsi` вже має `SANDBOXED_COMPILES=true` і сокет Docker на хості (`/var/run/docker.sock`) змонтований. 2. **Поле `PANDOC_IMAGE` має бути присутній** на тому Docker-хості (витягнутий або зібраний локально) до першої конвертації. *** ### Швидке налаштування Розробницький стек (`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 / microservices. # - `www-data` з UID 33 — ізольовані *sibling* контейнери Server Pro встановлюють # TEXLIVE_IMAGE_USER=www-data (див. /etc/overleaf/env.sh). clsi (запущений як # www-data) створює каталог конвертації з власником 33:33, тому контейнер має запускатися # як www-data(33), щоб записувати в нього — інакше pandoc завершується помилкою або # "unable to find user 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 ``` Для продакшену зафіксуйте `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://overleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/import-i-eksport-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.