مشاريع Typst
ثبّت نسخة Typst لكل مشروع، وأضف حزمًا من Typst Universe، وتحكم في الخطوط ومتغيرات البناء وملفات PDF القابلة لإعادة الإنتاج، وحوّل مشروع LaTeX إلى Typst.
يأتي Oleafly مع Typst 0.15.1 وخادم لغة Tinymist 0.15.8، لذا يُجمَّع مشروع Typst جديد دون تثبيت أي شيء. وتغطي هذه الصفحة ما يمكنك تغييره: أي نسخة من Typst يستخدمها المشروع، ومن أين تأتي حزمه وخطوطه، وكيف يبني مصدر واحد أكثر من ملف PDF. أما الصيغة وشريط الأدوات فابدأ بهما من الكتابة بـTypst.
نسخ 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 (انظر ذكاء الكود). ولكل إصدار فرعي من 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 | لا | لا | نعم | نعم |
| PDF موسوم في كل تجميع | لا | لا | لا | نعم |
يستطيع منتقي الخطوط أن يذكر مصدر كل خط في Typst 0.15 وما بعدها. وعندما يتعذر تطبيق إعداد على النسخة التي يستخدمها المشروع، توسمه قائمة التجميع بعبارة Needs a newer Typst.
حزم من Typst Universe
قسم بعنوان “حزم من 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”متغير البناء هو مجموعة قيم مسماة يقرؤها مستندك عبر sys.inputs. استخدم المتغيرات عندما يحتاج مصدر واحد إلى إنتاج ملفات PDF مختلفة، مثل نسخة تحكيم مجهولة الهوية ونسخة نهائية جاهزة للطباعة، أو مسودة بعلامة مائية.
المستند هو الذي يقرر ما تفعله كل قيمة. وتصل القيم دائمًا نصًا:
#let draft = sys.inputs.at("draft", default: "false") == "true"
#if draft [*Draft. Do not circulate.*]لإعداد متغير:
- افتح Document settings ومرر إلى Build variants.
- اختر Add variant وسمِّه، مثل
review. - اختر Add value، ثم أدخل
draftتحت Name وtrueتحت Value. - اختر Apply.
- افتح قائمة التجميع. تعرض 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 هو الافتراضي.

المعاينة الحية مع التجميع التلقائي
قسم بعنوان “المعاينة الحية مع التجميع التلقائي”اضبط Auto compile على On في قائمة التجميع. عندها، في مشروع Typst، يبقي Oleafly عملية Typst واحدة تعمل. يحفظ الملف المفتوح نفسه بعد لحظة من توقفك عن الكتابة، فيجمّعه Typst، وتُعاد تحميل المعاينة عند موضع التمرير نفسه. ولا يوجد إعداد منفصل للمعاينة الحية: التجميع التلقائي هو المعاينة الحية.
أثناء بدء تشغيل Typst، تعرض القائمة «Starting Typst». وإذا توقف بعد أخطاء متكررة، ذكرت القائمة ذلك، وأعاد تشغيله تعديلك التالي. وأنهى Stop compilation العملية، ويعيد التعديل التالي تشغيلها أيضًا. وتتعامل مشاريع LaTeX وMarkdown مع التجميع التلقائي بطريقة مختلفة؛ انظر التجميع.
البناء من سطر الأوامر
قسم بعنوان “البناء من سطر الأوامر”يبني الأمر oleafly المشاريع دون فتح التطبيق. وهو يأتي مع Oleafly، ويبيّن أداة سطر الأوامر كيف تضعه على 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 إلى 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 في صفحة الأدوات.
صفحات ذات صلة
قسم بعنوان “صفحات ذات صلة”- الكتابة بـTypst لشريط الأدوات ومستند أول.
- التجميع للسجلات وقائمة التجميع ووضع عدم الاتصال.
- تصدير المشروع وتحويله لصيغ PNG وSVG وHTML وPDF/A وPDF/UA.
- فحوصات Preflight للفحوصات التي تقرأ مصادر Typst.