> 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/ar/althyeh/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.** في حزمة التطوير `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 مخصصة لتحويلات sandboxed في clsi
# (الاستيراد/التصدير: docx / markdown / html، عبر ENABLE_PANDOC_CONVERSIONS).
#
# لماذا يوجد هذا:
#   صورة quay.io/sharelatex/pandoc:3.9 الرسمية خاصة (401، لا يمكن سحبها).
#   يستدعي clsi pandoc بشكل عام (من دون قوالب/مرشحات/مرجع-مستند مخصصة)، لذا فإن
#   صورة pandoc القياسية تعمل — فهي تحتاج فقط إلى ثلاثة أساسيات وقت التشغيل التي يفترضها clsi:
#
#   1. لا يوجد `pandoc` ENTRYPOINT — يشغّل clsi Cmd ["pandoc", ...]؛ ومع نقطة الدخول
#      الافتراضية سيصبح ذلك `pandoc pandoc ...`.
#   2. `zip` — الخطوة الثانية من تحويل الاستيراد تشغّل `zip -r` لحزم المخرجات.
#   3. مستخدمون يطابقون كيفية تشغيل clsi لحاوية التحويل (User=$TEXLIVE_IMAGE_USER):
#        - `tex` عند UID 1000 — القيمة الافتراضية للتطوير / الخدمات المصغّرة.
#        - `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" أو "تم رفض الإذن".
#      تأتي 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` إلى إصدار محدد بدلًا من `الأحدث` لعمليات بناء قابلة لإعادة الإنتاج، واضبط `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/ar/althyeh/overleaf-toolkit/pandoc-import-and-export.md?ask=<question>&goal=<endgoal>
```

`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.