> 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/ar/aliadadat/overleaf-toolkit/alastyrad-waltsdyr-bastkhdam-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 بشكل عام (من دون قوالب/مرشحات/مستند مرجعي مخصّصة)، لذا فإن
#   صورة 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 إما برسالة
#          "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` إلى إصدار محدد بدلًا من `الأحدث` لعمليات بناء قابلة لإعادة الإنتاج، واضبط `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/ar/aliadadat/overleaf-toolkit/alastyrad-waltsdyr-bastkhdam-pandoc.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.