> 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/uk/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 ``` * Тип: boolean (`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 — ізольовані *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 ``` Для 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/uk/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.