# مشاريع Typst

ثبّت نسخة Typst لكل مشروع، وأضف حزمًا من Typst Universe، وتحكم في الخطوط ومتغيرات البناء وملفات PDF القابلة لإعادة الإنتاج، وحوّل مشروع LaTeX إلى Typst.

يأتي Oleafly مع Typst 0.15.1 وخادم لغة Tinymist 0.15.8، لذا يُجمَّع مشروع Typst جديد دون تثبيت أي شيء. وتغطي هذه الصفحة ما يمكنك تغييره: أي نسخة من Typst يستخدمها المشروع، ومن أين تأتي حزمه وخطوطه، وكيف يبني مصدر واحد أكثر من ملف PDF. أما الصيغة وشريط الأدوات فابدأ بهما من [الكتابة بـTypst](/docs/writing/typst/).

## نسخ Typst

افتح **Settings → Engines → Typst**. البطاقة الأولى هي **Typst (built in)**، النسخة التي تأتي مع التطبيق. وإذا كانت هناك نسخة `typst` مثبتة على حاسوبك بالفعل، على `PATH` لديك، أو في مجلد Homebrew، أو في `~/.cargo/bin`، فستُظهر بطاقة ثانية هذه النسخة باسم **Typst on this computer**. ويمكن للمشاريع التي تثبّت تلك النسخة تحديدًا أن تُجمَّع بها.

وتحتهما، تعرض **Versions** نسخ Typst من 0.11 إلى 0.15، الأحدث أولًا. ويعطي كل صف تاريخ الإصدار وحجم التنزيل ومصدر النسخة (**Built in** أو **Downloaded** أو **System**)، وبعد التثبيت، إصدار Tinymist الذي يستخدمه.

- ينزّل **Install** تلك النسخة. يجرب Oleafly مرآته الخاصة أولًا ثم GitHub ثانيًا، ويتحقق من الأرشيف والبرنامج بداخله مقابل بصمات SHA-256 مدمجة في التطبيق. وأي ملف لا يطابق يُحذف، ولا يترك التثبيت الفاشل أو الملغى أي شيء خلفه. وتُحفظ التنزيلات في `~/.oleafly/toolchains/typst/`.
- الزر الدائري في يسار صف النسخة المثبتة يجعل تلك النسخة هي الافتراضية.
- يحذف **Remove** نسخة منزّلة. ولا يمكن حذف النسخة الافتراضية، فاختر افتراضية أخرى أولًا.

### النسخة الافتراضية وتثبيت النسخ في المشاريع

تثبّت مشاريع Typst الجديدة النسخة الافتراضية. وكذلك يفعل كل مشروع أُنشئ من قالب، والمشاريع المستوردة، والمجلدات المرتبطة. ويُخزَّن التثبيت في ملف `project.json` الخاص بالمشروع برقم نسخة لا بمسار، لذا يظل يعمل بعد أن تنقل المشروع أو تفتحه على حاسوب آخر.

تغيير الافتراضي لاحقًا لا ينقل المشاريع القائمة. وهذا مقصود: تحافظ الورقة المثبتة نسختها على فواصل الأسطر وعدد الصفحات نفسه عندما يصدر Oleafly نسخة Typst أحدث.

لتغيير نسخة مشروع واحد، افتح السهم المجاور لـ**Recompile** وانظر تحت **Typst version (this project)**. يتبع **Default** النسخة المختارة في Settings ويمحو التثبيت. أما الإدخالات الأخرى فهي النسخ المثبتة على هذا الحاسوب، وتحمل وسم **[built in]** أو **[system]** حيث ينطبق ذلك. ولاستخدام نسخة غير مدرجة، ثبّتها في Settings أولًا.

### عند غياب النسخة المثبتة

إذا فتحت مشروعًا يثبّت نسخة لا يملكها هذا الحاسوب، فلن يبنيه Oleafly بصمت بنسخة Typst مختلفة. يتوقف التجميع برسالة «Typst 0.13.1 is not installed»، وتعرض المعاينة زرين:

- يثبّت **Download Typst 0.13.1** النسخة المثبتة ويعيد التجميع. ويظهر عندما تكون النسخة مما يقدمه Oleafly.
- يمحو **Use Typst 0.15.1**، الذي يحمل اسم نسختك الافتراضية، التثبيت ويعيد التجميع بالنسخة الافتراضية.

وتوسم قائمة التجميع التثبيت بعلامة **[not installed]** حتى تختار أحدهما.

### جرّب نسخة أحدث قبل التبديل

مع فتح مشروع Typst، تعرض علامة تبويب Typst في Settings الخيار **Try a newer version** متى كانت هناك نسخة Typst أحدث مثبتة. اختر **Check with Typst 0.15.1** (أو أي نسخة يسميها الخيار). يبني Oleafly المشروع مرتين في مجلدات مؤقتة، مرة بنسخة المشروع الحالية ومرة بالنسبة الأحدث. ولا يتغير شيء في مشروعك.

يعرض التقرير ما إذا كان كل بناء قد نجح، وعدد صفحاته، وأخطاؤه وتحذيراته. ويخبرك إذا تغير عدد الصفحات. تسرد **New in Typst 0.15.1** الرسائل التي تبلغ عنها النسخة الأحدث وحدها، بينما تسرد **No longer reported by Typst 0.15.1** الرسائل التي تختفي. وانقر رسالة لفتح ملفها عند ذلك السطر.

إذا أعجبك ما تراه، فإن **Switch to Typst 0.15.1** يثبّت المشروع على النسخة الأحدث. ويعيد **Check again** تشغيل البناءين بعد أن تصلح شيئًا ما.

### خادم اللغة يتبع النسخة

يشغّل Tinymist الإكمال والمساعدة عند التحويم وإعادة التسمية والتنسيق في ملفات Typst (انظر [ذكاء الكود](/docs/code-intelligence/#typst-files)). ولكل إصدار فرعي من Typst إصدار Tinymist خاص به، ويتحدث المشروع مع الإصدار المطابق لنسخة Typst الخاصة به.

يغطي Tinymist المدمج نسخة Typst 0.15. وعندما تفتح مشروعًا مثبتًا على فرع أقدم، ينزّل Oleafly في الخلفية Tinymist المطابق، بالتحقق من البصمات نفسه، وتقرأ الحالة «Downloading Tinymist 0.13.30 to match this project's Typst version.» وإذا فشل التنزيل، أعاد Oleafly المحاولة لاحقًا. وعندما يجد Settings تنزيلات Tinymist لم تعد بحاجة إليها أي نسخة Typst مثبتة، يعرض **Remove unused language server downloads**.

### ما تستطيعه كل نسخة

توجد النسخ الأقدم لتبقى المشاريع التي بدأت عليها تُبنى بالطريقة نفسها. وتعتمد بعض الميزات على ما تدعمه نسخة Typst نفسها:

| الميزة | 0.11 | 0.12 | 0.13 | 0.14 وما بعدها |
| --- | --- | --- | --- | --- |
| خطوط المشروع فقط | لا | نعم | نعم | نعم |
| بناء قابل لإعادة الإنتاج | لا | نعم | نعم | نعم |
| نطاقات الصفحات في تصدير PNG وSVG | لا | نعم | نعم | نعم |
| PDF/A | لا | PDF/A-2b | PDF/A-2b، PDF/A-3b | كل مستويات PDF/A التي يقدمها Typst |
| PDF/UA-1 | لا | لا | لا | نعم |
| حزم محفوظة في مجلد المشروع | لا | نعم | نعم | نعم |
| تصدير HTML، وتصدير Word أو Markdown عبر HTML الخاص بـTypst | لا | لا | نعم | نعم |
| [مزامنة المصدر مع PDF](/docs/synctex/) | لا | لا | نعم | نعم |
| PDF موسوم في كل تجميع | لا | لا | لا | نعم |

يستطيع منتقي الخطوط أن يذكر مصدر كل خط في Typst 0.15 وما بعدها. وعندما يتعذر تطبيق إعداد على النسخة التي يستخدمها المشروع، توسمه قائمة التجميع بعبارة **Needs a newer Typst**.

## حزم من Typst Universe

اختر **Typst packages**، أيقونة الحزم في الطرف الأيمن من شريط أدوات Typst. وابحث في Typst Universe بالاسم أو الكلمة المفتاحية أو الفئة. وتعرض كل حزمة أحدث نسخة منها، والحزمة التي تحتاج نسخة Typst أحدث من التي يستخدمها المشروع تقول ذلك صراحة: «Needs Typst 0.14.0. This project uses Typst 0.13.1.»

يكتب **Insert import** سطر `#import` أعلى ملف Typst المفتوح. أما **Copy import** فيضعه في الحافظة بدلًا من ذلك.

ينزّل Typst حزمة `@preview` في المرة الأولى التي يستوردها فيها تجميع، ويحتفظ بها في ذاكرة تخزين مؤقت تشاركها كل المشاريع. وتُخزَّن قائمة الحزم مؤقتًا أيضًا. وفي وضع عدم الاتصال، يعرض مربع الحوار آخر قائمة جلبها، مع تاريخها.

### الإصدارات الأحدث

عندما يذكر الاستيراد إصدارًا أقدم من الإصدار الموجود على Typst Universe، يُسطَّر رقم نسخته مع تلميح مثل «cetz 0.4.2 is available. This import uses 0.3.4.» وتعرض بطاقة التلميح **Update to 0.4.2**، التي تغير رقم النسخة في الاستيراد. واقرأ سجل تغييرات الحزمة قبل أن تقبل ذلك، لأن الإصدار الجديد قد يغير طريقة استدعاء الحزمة. ويوفر التحويم فوق استيراد أيضًا خيار **Open on Typst Universe**.

### إبقاء الحزم داخل المشروع

تحت **Project packages** في مربع الحوار نفسه، ينسخ **Vendor packages into project** كل حزمة يستوردها المشروع إلى مجلد `typst-packages` في أعلى المشروع. وينسخ أيضًا الحزم التي تستوردها تلك الحزم، ويفعّل **Use packages from the project folder**.

من تلك اللحظة يبحث Typst في `typst-packages` أولًا. ويُجمَّع المشروع المضمّنة حزمه دون اتصال وعلى أي حاسوب، ويمكن إدخال المجلد إلى Git مع مصدرك. أما الحزمة التي لم تضمّنها فتظل تأتي من الذاكرة المؤقتة المشتركة. ويحتاج هذا إلى Typst 0.12 أو أحدث، وفي مشروع مثبّت على 0.11 يطلب منك مربع الحوار أن تبدّل النسخة أولًا.

وإذا لم تكن حزمة في الذاكرة المؤقتة بعد، فإن مربع الحوار يسمّيها: «These packages aren't in the package cache: …». جمّع مرة واحدة وأنت متصل، ثم ضمّن الحزم مرة أخرى.

### وضع عدم الاتصال

مع تفعيل **Offline mode** في **Settings → General**، لا يستطيع Typst تنزيل أي شيء. ويجب أن تكون كل حزمة في الذاكرة المؤقتة المشتركة أو في `typst-packages` مسبقًا. وإذا لم تكن كذلك، فشل التجميع وسمّت الرسالة الحزمة، لتعرف ما تجلبه في المرة القادمة التي تكون فيها متصلًا.

## الخطوط

يجد Typst الخطوط في أربعة أماكن: الخطوط المدمجة في Typst، والخطوط المثبتة على حاسوبك، وحزم الخطوط التي تنزّلها في Oleafly، ومجلدات الخطوط داخل المشروع. ضع ملفات الخطوط في مجلد باسم `fonts` في أعلى المشروع، فيلتقطها المجمّع وخادم اللغة معًا. ويمكن إدراج مجلدات إضافية تحت `typst.font_paths` في `project.json`. أما المجلدات خارج المشروع فتُهمَل.

تحت **Fonts (this project)** في قائمة التجميع، يكون **Use system fonts** هو الافتراضي. ويمنع **Project fonts only** Typst من قراءة الخطوط المثبتة على هذا الحاسوب. عندها يخرج ملف PDF بالشكل نفسه على كل جهاز، وإذا طلب المستند خطًا لا يتضمنه المشروع، علمت ذلك على حاسوبك أنت بدل حاسوب مشارك في التأليف.

لاختيار خط المتن، افتح **Document settings**، أيقونة المنزلقات في شريط أدوات Typst، وانقر **Body font**. تعرض القائمة كل عائلة يجدها Typst بإعدادات الخطوط الحالية للمشروع. وفي Typst 0.15 وما بعدها تحمل كل عائلة وسم **Project** أو **System** أو **Font pack** أو **Built in**. اختر واحدة ثم اختر **Apply**، فيكتبها Oleafly في قواعد `#set` الخاصة بالمستند.

### حزم الخطوط

تضم **Settings → Downloads → Fonts** خمس حزم خطوط مجانية لـTypst: **Chinese, Japanese and Korean** و**Classic text** و**Modern sans and serif** و**Code** و**Icons and emoji**. وبعد أن تُنزَّل حزمة، يستطيع كل مشروع Typst استخدام خطوطها بالاسم، وكذلك الأمر في تنزيلات Lato وPT Sans وPT Serif في ذلك التبويب. ولا تنضم الحزمة إلى عمليات التجميع إلا بعد انتهاء تنزيلها كله، فلا يؤثر تنزيل نصف مكتمل في أي بناء أبدًا.

المشاريع المضبوطة على **Project fonts only** أو **Reproducible build** لا تقرأ حزم الخطوط. وفي هذه الحالة انسخ ملف الخط إلى مجلد `fonts` في المشروع.

### أحرف تظهر مربعات

بعد كل تجميع، يفحص Oleafly وجود أحرف لا يستطيع أي خط متاح رسمها. ويرسمها Typst مربعات. وحين يجد أيًّا منها، يحصل التجميع على تنبيه وتظهر ملاحظة فوق المحرر:

- **المربعات الفارغة** تعني أنه لا خط يستطيع Typst استخدامه يحوي الأحرف، ويسمّي التنبيه بعضها. وحين تغطيها حزمة خطوط، كما تغطي حزمة Chinese, Japanese and Korean نص CJK وحزمة Icons and emoji الرموز التعبيرية، تعرض الملاحظة **Download fonts** مع حجم التنزيل، ويعرض السجل **Download and compile**. وإلا فأضف خطًا يحويها إلى مجلد `fonts` في المشروع.
- **المربعات التي فيها علامة استفهام** تعني أن Typst رسم الأحرف بخط بديل. سمِّ خطًا يحويها تحت **Body font** في **Document settings**، أو في قائمة خطوط مثل `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`.
- في مشروع مضبوط على **Project fonts only**، لا تنطبق حزم الخطوط ولا خطوط النظام. أضف خطًا إلى مجلد `fonts`، أو بدّل المشروع إلى **Use system fonts** و**Standard build**.

يفتح **Document settings** في الملاحظة اللوحة التي تختار منها خط المتن. وأغلق الملاحظة لإخفائها لذلك التنبيه.

## متغيرات البناء وsys.inputs

متغير البناء هو مجموعة قيم مسماة يقرؤها مستندك عبر `sys.inputs`. استخدم المتغيرات عندما يحتاج مصدر واحد إلى إنتاج ملفات PDF مختلفة، مثل نسخة تحكيم مجهولة الهوية ونسخة نهائية جاهزة للطباعة، أو مسودة بعلامة مائية.

المستند هو الذي يقرر ما تفعله كل قيمة. وتصل القيم دائمًا نصًا:

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

لإعداد متغير:

1. افتح **Document settings** ومرر إلى **Build variants**.
2. اختر **Add variant** وسمِّه، مثل `review`.
3. اختر **Add value**، ثم أدخل `draft` تحت **Name** و`true` تحت **Value**.
4. اختر **Apply**.
5. افتح قائمة التجميع. تعرض **Variant (this project)** الآن `review`. اخترها وجمّع.

يبني **No variant** دون أي قيم متغيرات. ويُحفظ المتغير الذي تختاره على هذا الحاسوب فقط، فيستطيع مشارك في التأليف بناء متغير آخر من المشروع نفسه. أما المتغيرات نفسها فتُحفظ في `project.json`. وتستخدم عمليات التصدير المتغير المختار أيضًا.

القيم التي يجب أن يحصل عليها كل بناء توضع تحت `typst.inputs` في `project.json`. وعندما يعيّن متغير قيمة بالاسم نفسه، فالمتغير هو الذي يسود.

## عمليات بناء قابلة لإعادة الإنتاج

تحت **Build (this project)** في قائمة التجميع، يجعل **Reproducible build** المصادر نفسها تعطي ملف PDF نفسه على أي حاسوب. فهو لا يستخدم إلا خطوط المشروع والخطوط المدمجة في Typst، ويؤرخ ملف PDF بآخر إيداع Git. ويحصل المشروع الذي ليس مستودع Git على تاريخ ثابت هو 1 يناير 1970.

يهم هذا عندما يجب أن يطابق ملف PDF بصمة تحقق، لإيداع في أرشيف أو للمقارنة في CI. وهو يحتاج Typst 0.12 أو أحدث. وعندما يكون مفعلًا، يصبح **Use system fonts** غير متاح. و**Standard build** هو الافتراضي.

![يُجمَّع Typst أثناء الكتابة: يظهر كل سطر جديد في ملف PDF.](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## المعاينة الحية مع التجميع التلقائي

اضبط **Auto compile** على **On** في قائمة التجميع. عندها، في مشروع Typst، يبقي Oleafly عملية Typst واحدة تعمل. يحفظ الملف المفتوح نفسه بعد لحظة من توقفك عن الكتابة، فيجمّعه Typst، وتُعاد تحميل المعاينة عند موضع التمرير نفسه. ولا يوجد إعداد منفصل للمعاينة الحية: التجميع التلقائي هو المعاينة الحية.

أثناء بدء تشغيل Typst، تعرض القائمة «Starting Typst». وإذا توقف بعد أخطاء متكررة، ذكرت القائمة ذلك، وأعاد تشغيله تعديلك التالي. وأنهى **Stop compilation** العملية، ويعيد التعديل التالي تشغيلها أيضًا. وتتعامل مشاريع LaTeX وMarkdown مع التجميع التلقائي بطريقة مختلفة؛ انظر [التجميع](/docs/compiling/#auto-compile).

## البناء من سطر الأوامر

يبني الأمر `oleafly` المشاريع دون فتح التطبيق. وهو يأتي مع Oleafly، ويبيّن [أداة سطر الأوامر](/docs/cli/#install) كيف تضعه على PATH لديك.

في مشروع Typst، يقرأ الأمران `oleafly build` و`oleafly watch` ملف `project.json` ويستخدمان الإعدادات نفسها التي يستخدمها التطبيق: النسخة المثبتة، والحزم المضمّنة، ومجلدات الخطوط، ومفتاح خطوط النظام، والمدخلات، وعمليات البناء القابلة لإعادة الإنتاج.

- يبني `--variant review` متغيرًا. والاسم الذي لا يعرّفه المشروع يوقف البناء، وتسرد الرسالة المتغيرات الموجودة فعلًا.
- يمنع `--offline` تنزيل الحزم، مثل وضع عدم الاتصال في التطبيق.
- المشروع المثبت نسخته لا يُبنى إلا بذلك الـTypst بعينه. ينظر الـCLI إلى `OLEAFLY_TYPST`، ثم النسخ التي نزّلها التطبيق، ثم `typst` المجاور للـCLI، ثم `PATH` لديك. وإذا لم يبلغ أي منها عن النسخة المثبتة، توقف البناء قبل تشغيل Typst وأخبرك بكيفية تثبيتها.
- يستخدم المشروع بلا تثبيت `OLEAFLY_TYPST` إذا كان معيّنًا. وإلا فيستخدم النسخة الافتراضية التي اخترتها في **Settings → Downloads** أو بالأمر `oleafly typst default`، وإذا لم تختر نسخة افتراضية فيستخدم Typst المدمج أو ما على `PATH` لديك.
- يسرد `oleafly doctor` كل نسخة Typst وجدها والإعدادات التي سيستخدمها البناء. ويفشل عندما تكون النسخة المثبتة مفقودة.

وإذا تعذر تطبيق إعداد على نسخة Typst المستخدمة، طبع البناء ملاحظة، مثل أن Typst 0.11.1 لا يستطيع تجاهل خطوط النظام. وتتضمن الأخطاء في الطرفية تلميحات Typst نفسها.

## تحويل مشروع LaTeX إلى Typst

افتح مشروع LaTeX، واضغط ⌘K (Ctrl+K)، وشغّل **Convert to a Typst project**. أعطِ المشروع الجديد اسمًا واختر **Convert**. يبقى مشروع LaTeX كما كان تمامًا. ويبني Oleafly منه مشروع Typst منفصلًا:

- يحوّل Pandoc النص والرياضيات والأشكال والجداول. وإذا لم يكن Pandoc مهيأً بعد، هيّأه Oleafly أولًا.
- يصبح كل ملف مُدخَل عبر `\input` أو `\include` أو `\subfile` ملف `.typ` خاصًا به.
- تُنسخ ملفات BibTeX دون تغيير.
- يجمّع Typst المشروع الجديد للتحقق منه.

يقول التقرير بعد ذلك ما إذا كان المشروع يُجمَّع، ويعدّ ما تم تحويله: ملفات المصدر، والأشكال، والجداول، والمعادلات المعروضة، والإحالات المرجعية، والصيغ التي أصلحها محول الرياضيات، والملفات المنسوخة، مع نمط التوثيق الذي اختاره. وتسرد **Needs attention** ما يجب إصلاحه يدويًا، مثل تضمين أو صورة مفقودة، أو صيغة صورة لا يستطيع Typst عرضها، أو رياضيات لم يتمكن المحول من معالجتها، أو نمط BibTeX بلا مقابل في Typst، أو وسم على سطر واحد من معادلة متعددة الأسطر صار يشير الآن إلى المعادلة كلها. وترتبط أخطاء التجميع وتحذيراته بملفها وسطرها.

اختر **Open the Typst project** للانتقال إليه. ويثبّت المشروع الجديد نسخة Typst الافتراضية لديك. وطوال بقاء Oleafly مفتوحًا، يعيد **Show the Typst conversion report** في لوحة الأوامر إظهار التقرير.

ولتحويل ملف واحد بدلًا من مشروع كامل، استخدم [LaTeX إلى Typst](/docs/tools/latex-to-typst/) في صفحة الأدوات.

## صفحات ذات صلة

- [الكتابة بـTypst](/docs/writing/typst/) لشريط الأدوات ومستند أول.
- [التجميع](/docs/compiling/) للسجلات وقائمة التجميع ووضع عدم الاتصال.
- [تصدير المشروع وتحويله](/docs/export/#typst-images-and-html) لصيغ PNG وSVG وHTML وPDF/A وPDF/UA.
- [فحوصات Preflight](/docs/preflight/#typst-projects) للفحوصات التي تقرأ مصادر Typst.
