# الكتابة في Typst

اكتب ورقة بحثية أو تقريرًا أو سيرة ذاتية بلغة Typst في وضع Code أو Visual، مع شريط أدوات يكتب ترميز Typst نيابةً عنك.

اختر قالب Typst وحرِّر مصدر `.typ` الخاص به بجوار ملف PDF المجمَّع. يكتب لك شريط الأدوات صياغة Typst، فيبقى كل تغيير في المصدر حيث يمكنك قراءته وتحريره. وحين لا تريد النظر إلى الترميز، بدِّل الملف إلى الوضع المرئي.

![مثال Typst مع شريط تنسيقه ومصدره وتقريره المجمَّع.](https://cdn.oleafly.com/images/screenshots/desktop/docs/typst-writing-dark-window-v2.png)

## تجميع تقرير صغير

1. اختر **New project → Use a template → Blank Typst document**.
2. سمِّه **ملاحظة القياس** وافتح `main.typ`.
3. الصق المثال أدناه، ثم اختر **Recompile** أو اضغط **⌘Enter / Ctrl+Enter**.

```typst title="main.typ"
#set document(title: "Measurement note", author: "Alex Chen")
#set page(paper: "a4", margin: 25mm)
#set heading(numbering: "1.")

= Measurement note
A short report on repeated measurements.

== Method <method>
We collect three observations and compare their mean.

$ overline(x) = (1 + 2 + 3) / 3 = 2 $

== Results
See @method for the procedure.

#table(
  columns: 2,
  [Run], [Value],
  [1], [1],
  [2], [2],
  [3], [3],
)
```

ينبغي أن يعرض ملف PDF عناوين مرقّمة ومعادلة عرض وإحالة مرجعية إلى الطريقة وجدولًا من عمودين.

لمشاهدة تغيّر ملف PDF أثناء الكتابة، افتح السهم المجاور لـ**Recompile** واضبط **Auto compile** على **On**. في مشروع Typst، هذا هو المعاينة الحية. انظر [المعاينة الحية مع التجميع التلقائي](/docs/typst/#live-preview-with-auto-compile).

[تنزيل مصدر المثال](/examples/writing-example.typ)

## كل أدوات شريط الأدوات

حدِّد نصًا قبل استخدام أداة تنسيق ليطوّق ذلك النص. ومن دون تحديد، يُدرج شريط الأدوات عنصرًا نائبًا يمكنك الكتابة فوقه. وحين يكون المحرر أضيق من أن يتسع لكل زر، تنتقل الأزرار التي لا تتسع إلى **More formatting options** (`…`). وتوجد معظم هذه الأدوات أيضًا في قائمة النقر بالزر الأيمن في المحرر.

### Code / Visual

يغيّر المفتاح في بداية شريط الأدوات طريقة عرض الملف. يعرض **Code** مصدر Typst. ويرسم **Visual** العناوين والتوكيد والقوائم والرياضيات والصور والجداول والإحالات المرجعية والحواشي السفلية في مواضعها، ويعيد إظهار المصدر في السطر الذي يقف عنده مؤشرك. الملف هو نفسه في الوضعين. التفاصيل في [الوضع المرئي في Typst](#visual-mode).

### Undo

يتراجع عن آخر تعديل. ⌘Z / Ctrl+Z. يظهر الزر باللون الرمادي حين لا يوجد ما يُتراجع عنه.

### Redo

يعيد تطبيق تعديل تراجعت عنه. **⌘Shift+Z / Ctrl+Shift+Z**.

### Heading → Title

حدِّد عنوانًا واختر **Title**. `= Title`.

### Heading → Section

يضيف قسمًا داخل المستند. `== Section`.

### Heading → Subsection

يضيف مستوى تحت القسم. `=== Subsection`.

### Heading → Subsubsection

يضيف عنوانًا من المستوى الرابع. `==== Subsubsection`.

### Heading → Minor heading

يضيف عنوانًا من المستوى الخامس. `===== Minor heading`.

### Heading → Paragraph heading

يضيف عنوانًا من المستوى السادس. `====== Paragraph heading`.

### Bold

حدِّد «three observations». `*three observations*`؛ ⌘B / Ctrl+B.

### Italic

حدِّد مصطلحًا لتوكيده. `_term_`؛ ⌘I / Ctrl+I.

### Underline

حدِّد عبارة. `#underline[phrase]`.

### Strikethrough

علِّم عبارة لم تعد معتمدة. `#strike[phrase]`.

### Inline code

حدِّد اسم ملف أو اسم متغير. يطوّقه بعلامتَي الاقتباس الخلفيتين.

### Insert link

استبدل `url` ثم `text`. `#link("url")[text]`.

### Cite from project

ابحث في قائمة مراجع المشروع بالمفتاح أو المؤلف أو العنوان، واختر مدخلًا. يكتب Oleafly `@key`. وإذا لم يكن في المستند استدعاء `#bibliography` بعد، أضافه Oleafly. ويفتح **Find and add a new citation…** أسفل القائمة البحثَ عن مصدر جديد. انظر [إضافة استشهادات](#add-citations).

### Insert cross-reference

اختر تسمية من قائمة المشروع لتكتب `@label`. في المثال، اختر `method` لتحصل على `@method`. أما **Add a label here** فيضع تسمية جديدة على العنصر الواقف عنده المؤشر.

### Add label

ضع المؤشر في عنوان أو شكل أو معادلة واختر **Add label**. على عنوان Results في المثال، يضيف Oleafly `<sec:results>`. وإذا كان للعنصر تسمية بالفعل، حدَّدها الزر.

### Insert footnote

ضع المؤشر بعد كلمة. `#footnote[note text]`.

### Insert blockquote

ضع المؤشر في سطر جديد. `#quote(block: true)[quote]`.

### Insert figure

يفتح مربع حوار الأشكال. اختر صورة من **Project images** أو اختر **Import from disk…**، ثم اضبط عرضها وعنوانها التوضيحي وتسميتها ونصها البديل وموضعها. ومع وجود المؤشر داخل `#figure` قائم، يفتح الزر نفسه **Edit figure** لتغيير أي من ذلك. انظر [إضافة شكل بعنوان توضيحي](#add-a-captioned-figure).

### Insert table

افتح الشبكة واختر عدد الصفوف والأعمدة. يُدرج Oleafly `#figure` يحوي `table` بصف رأس وخطوط علوية ووسطى وسفلية، مع `caption: [Caption]` والتسمية `<tab:label>`. استبدل العنوان التوضيحي والتسمية والخلايا الفارغة. ولبناء جدول من ملف بيانات جدولية بدلًا من ذلك، انظر [جداول من ملفات البيانات](#tables-from-data-files).

### Insert image

استورد صورة، ثم استبدل اسم الملف المحدد بمسارها النسبي. `#image("image-filename")`. ويمكنك أيضًا لصق ملف صورة أو إفلاته في المحرر، فيحفظه Oleafly في المشروع ويُدرج شكلًا يستخدمه.

### Draw a diagram

يفتح [محرر المخططات](/docs/figures-diagrams/) في وضع Typst. ارسم على اللوحة أو حرِّر شيفرة fletcher، ثم اختر **Insert as Typst** لوضع المخطط عند المؤشر. تنزِّل المعاينة الأولى حزمة fletcher من Typst Universe، لذا يجب أن تكون متصلًا بالإنترنت لأجلها.

### Image to Typst

اختر لقطة شاشة لمعادلة أو بعض النص، فيُنسخ محتواها إلى Typst عند المؤشر. يستخدم نموذج Tools، وهو نموذج Ollama محلي ما لم تختر غيره. وإذا لم تكن قد اخترت واحدًا، ولم يكن Ollama يعمل أو لم يكن فيه نموذج يقرأ الصور، فإنه يستخدم نموذج المساعد بدلًا من ذلك، وتذهب الصورة إلى ذلك المزوّد. تحقق من النتيجة ثم جمِّعها.

### List → Bulleted list

يبدأ قائمة ملاحظات. `- Item`.

### List → Numbered list

يبدأ تسلسلًا من الخطوات. `+ Item`.

### Math

حدِّد `x` وانقر أيقونة الرياضيات. `$x$`.

### Display equation

معادلة في سطر مستقل. `$ x $`، مع مسافة داخل كل `$`.

### Numbered equation

معادلة عرض ذات تسمية، مثل `$ x $ <eq:label>`. لا يرقّم Typst المعادلات إلا حين تكون في المستند قاعدة ترقيم. وإذا لم يكن في مستندك واحدة، قدَّمت ملاحظة خيار **Add rule**، الذي يضيف `#set math.equation(numbering: "(1)")` قرب أعلى الملف.

### Aligned equations

عدة معادلات متحاذية عند `&`، مع `\` بين الصفوف. `$ a &= b \ c &= d $`.

### Fraction

يُدرج `frac(a, b)`، محاطًا بـ`$` حين لا يكون المؤشر في الرياضيات بالفعل. ومع وجود نص محدد، يصبح التحديد هو البسط.

### Symbols

افتح منتقي الرموز، وابحث عن رمز، وحدِّده. يكتبه Oleafly باسمه في Typst: `arrow.r` داخل الرياضيات، أو `#sym.arrow.r` في النص الجاري.

### Code block

حدِّد عدة أسطر من الشيفرة أو استبدل العنصر النائب. كتلة محاطة بثلاث علامات اقتباس خلفية. أضف لغة بعد علامة البداية للحصول على تلوين الصياغة.

### Code intelligence → Go to definition

ضع المؤشر على تسمية أو متغير أو دالة واختر الإجراء، أو اضغط F12. يفتح موضع تعريفه، ولو كان في ملف آخر.

### Code intelligence → Find references

يسرد كل موضع تُستخدم فيه التسمية أو المتغير أو الدالة. ⇧F12.

### Code intelligence → Rename symbol

يعيد تسمية تسمية أو متغير أو دالة عبر المشروع كله. F2. ويغطي [ذكاء الكود](/docs/code-intelligence/#typst-files) الثلاثة جميعًا.

### Typst packages

تبحث أيقونة الحزم في الطرف الأيمن من الشريط في Typst Universe وتُدرج سطر `#import`. المزيد تحت [الحزم والإعدادات والرؤى](#packages-settings-and-insights).

### Document insights

يسرد عناوين المستند وأشكاله وجداوله ومعادلاته وتسمياته واستشهاداته وبنود مهامه، وكل عنصر منها مرتبط بسطره. انظر [رؤى المستند](/docs/document-insights/).

### Document settings

يغيّر حجم الصفحة والهوامش والخط واللغة والضبط وتباعد الأسطر والترقيم بتحرير قواعد `#set` الخاصة بالمستند. انظر [إعدادات المستند](/docs/document-settings/).

### Project info

يعرض إحصاءات الكلمات والأشكال والرياضيات للمستند ولأي تحديد، إلى جانب نتائج التدقيق اللغوي.

### Find

ابحث عن كلمة في الملف النشط. ⌘F / Ctrl+F.

### Go to PDF

ينتقل من المؤشر إلى الموضع المقابل في ملف PDF المجمَّع. يظهر الزر في Typst 0.13 وما بعده. انظر [الانتقال بين المصدر وملف PDF](#jump-between-the-source-and-the-pdf).

## الوضع المرئي

بدِّل شريط الأدوات من **Code** إلى **Visual** في أي ملف `.typ`. الوضع المرئي هو المحرر نفسه مع رسم الترميز في موضعه:

- العناوين، والنص العريض والمائل، والنص الخام، والروابط، والنص الملون
- القوائم النقطية والرقمية وقوائم المصطلحات مع علاماتها
- الرياضيات المضمنة والمعروضة، مرسومة بواسطة Typst
- الصور والأشكال، مع العنوان التوضيحي معروضًا نصًا
- الجداول شبكة يمكن الكتابة داخلها. حدِّد خلية فيظهر شريط أدوات صغير للحدود والمحاذاة والصفوف والأعمدة.
- المراجع والاستشهادات على شكل شرائح، والحاشيات السفلية علامة صغيرة

ضع المؤشر في سطر فيعود مصدره لتحريره. وابتعد عنه فيعود الشكل المعروض. تنطوي أسطر `#set` و`#show` و`#import` و`#let` في أعلى الملف إلى شريط **Show document settings**، انقره لتفتحها. وما لا يستطيع الوضع المرئي رسمه يبقى على الشاشة مصدرًا. وكل زر في شريط الأدوات يكتب Typst نفسه في الوضعين، وتبقى أرقام الأسطر والبحث والتدقيق الإملائي وأخطاء التجميع تعمل.

تُفتح المشاريع الجديدة في وضع Code، ويتذكر كل مشروع الوضع الذي تركته فيه. ويغطي [التحرير المرئي](/docs/editor/#visual-editing) التبديل في اللغات الثلاث.

## مساعدة أثناء الكتابة

تحصل ملفات Typst على المساعدات نفسها المتاحة لملفات LaTeX، مكتوبة لصياغة Typst:

- انقر السهم في شريط الأرقام الجانبي لطي عنوان حتى العنوان التالي من المستوى نفسه. وتُطوى أيضًا كتل الشيفرة وكتل المحتوى والمعادلات وقوائم المعاملات الطويلة. انظر [طي الأكواد](/docs/editor/#code-folding).
- أثناء التمرير، تبقى العناوين الواقعة فوق المؤشر مثبتة في أعلى المحرر. ويذكر شريط مسار التنقل فوق الملف اسم القسم الذي تقف فيه، والنقر على عنصر منه ينقلك إلى ذلك العنوان.
- كتابة `$` تضيف `$` الختامية، ومسافة داخل الزوج الفارغ تحوّله إلى معادلة عرض. وعلى بند في قائمة، يبدأ Enter البند التالي. ويسرد [مساعدات الكتابة في Typst](/docs/editor/#typst-typing-aids) البقية.
- يكمل خادم لغة Typst الدوال ومسارات الملفات والتسميات ومفاتيح الاستشهادات والحزم وأنماط قوائم المراجع. انظر [إكمال Typst](/docs/autocomplete/#typst-completion).
- اكتب `/` في بداية سطر، أو بعد مسافة، لإدراج مقاطع: عناوين وأشكال وجداول ومعادلات وحواشٍ سفلية وفهرس وقائمة مراجع وغيرها.
- يعلِّق ⌘/ / Ctrl+/ الأسطر المحددة أو يزيل تعليقها بـ`//`.

### معاينة الرياضيات

مع وجود المؤشر داخل معادلة، يرسم Typst النتيجة فوقها مباشرة. وتستطيع قائمة المعاينة إخفاءها إلى أن تغادر المعادلة، أو إيقافها تمامًا.

الصق رياضيات LaTeX مثل `$\frac{a}{b}$` في ملف Typst، فيظهر زر **Paste as Typst math** تحتها. انقره لتستبدل ما لصقته برياضيات Typst، أو اضغط Esc للإبقاء على LaTeX. أما الرياضيات الموجودة سلفًا في الملف فحدِّدها واختر **Convert LaTeX math to Typst** من قائمة النقر بالزر الأيمن. وللتحويلات لمرة واحدة، تقوم أداة [Equation to Typst](/docs/tools/equation-to-typst/) بالعملية نفسها خارج المشروع.

## إضافة شكل بعنوان توضيحي

1. اختر **Insert figure** من شريط الأدوات.
2. اختر `plot.png` تحت **Project images**، أو اختر **Import from disk…** لنسخها إلى المشروع.
3. اختر **Three-quarter width**، ثم فعِّل **Add a caption** و**Add a label**. أدخل العنوان التوضيحي والتسمية `fig:measurements`.
4. أضف **Alt text** يصف الصورة لقارئات الشاشة، واختر **Placement** إن وجب أن يطفو الشكل إلى أعلى الصفحة أو أسفلها.
5. اختر **Insert figure**.

يكتب Oleafly شكلًا كهذا:

```typst
#figure(
  image("figures/plot.png", width: 75%),
  caption: [Measurements across three runs.],
) <fig:measurements>

See @fig:measurements for the comparison.
```

لتغيير الشكل لاحقًا، ضع المؤشر داخله واختر **Insert figure** مرة أخرى. يفتح مربع الحوار باسم **Edit figure** وبالقيم الحالية.

## جداول من ملفات البيانات

انقر بالزر الأيمن في المحرر واختر **Table from CSV/XLSX…**. اختر ملف CSV أو TSV أو Excel أو JSON، وتفقَّد المعاينة، وأضف عنوانًا توضيحيًا وتسمية إن أردتهما. يكتب **Insert at cursor** جدول Typst بالقواعد نفسها التي يستخدمها جدول شريط الأدوات. ويُهرَّب نص الخلايا الذي كان Typst سيقرؤه ترميزًا.

فعِّل **Keep linked to the data file** ليبقى الجدول مرتبطًا ببياناته. ينسخ Oleafly البيانات إلى مجلد `data` في المشروع، ويقرأ الجدول ذلك الملف في كل مرة يُجمَّع فيها المستند. حرِّر الملف فيتغير الجدول عند التجميع التالي. ويغطي [استيراد جدول من ملف بيانات](/docs/writing/tables-equations/#import-a-table-from-a-data-file) مربع الحوار بالكامل.

## إضافة استشهادات

استشهد باستخدام **Cite from project**، أو اكتب `@` واختر مفتاحًا من قائمة الإكمال. مفتاح الاستشهاد وتسمية المستند كلاهما يستخدم `@` في Typst؛ وقائمة المراجع أو التسمية هي التي توفر الهدف.

ضع قائمة المراجع حيث تريد أن تظهر قائمة المصادر:

```typst
#bibliography("references.bib")
```

يمكن أن يكون الملف BibTeX (`.bib`) أو Hayagriva (`.yml`)، ويمكن للاستدعاء أن يسمّي قائمة من الملفات. والاستشهاد الذي تضيفه من [الاستشهادات وقوائم المراجع](/docs/citations/) يدخل في الملف الذي يعلنه المستند، محولًا إلى Hayagriva حين يحتاج ذلك الملف إليه. ولتغيير نمط التوثيق، استخدم قائمة **Citation style** أسفل لوحة المراجع، فتكتب معامل `style:` نيابةً عنك. انظر [اختيار نمط استشهاد Typst](/docs/citations/#choose-a-typst-citation-style).

## الحزم والإعدادات والرؤى

ثلاثة أزرار في الطرف الأيمن من شريط الأدوات تعمل على المستند كله:

- يبحث **Typst packages** في Typst Universe ويكتب سطر `#import`. وحين يسمّي الاستيراد إصدارًا أقدم، يعرض المحرر تحديثه. ويمكن للمشروع أيضًا أن يحتفظ بنسخه الخاصة من حزمه ليُجمَّع دون اتصال. انظر [الحزم](/docs/packages/#typst-packages) و[حزم من Typst Universe](/docs/typst/#packages-from-typst-universe).
- يسرد **Document insights** العناوين والأشكال والجداول والمعادلات والتسميات والاستشهادات وبنود المهام، وينسخ العنوان والمؤلفين والكلمات المفتاحية والملخص لنموذج تقديم. يقرأ Typst المستند حين يفتح مربع الحوار، فتكون الأرقام والصفحات محدَّثة. انظر [رؤى المستند](/docs/document-insights/).
- يغيّر **Document settings** حجم الصفحة والهوامش والأعمدة وخط المتن وحجمه واللغة والضبط وتباعد الأسطر وترقيم العناوين والمعادلات. يكتب Oleafly اختياراتك في قواعد `#set` الخاصة بالملف الرئيسي. وهو يحتفظ أيضًا بمتغيرات بناء المشروع. انظر [إعدادات المستند](/docs/document-settings/).

## الأخطاء والفحوصات

حين يفشل التجميع، يُسطَّر كل خطأ في ملفه، فوق المدى نفسه الذي يبلِّغ عنه Typst. مرِّر المؤشر فوق التسطير لقراءة الرسالة وتلميحات Typst. وتأتي الأخطاء الشائعة، مثل اسم غير معروف أو ملف أو حزمة مفقودة أو قوس غير مغلق، مع شرح بلغة مبسطة. انظر [أخطاء التجميع في المصدر](/docs/editor/#compile-errors-in-the-source).

يفحص [الإملاء والقواعد](/docs/spellcheck-grammar/) النصوص في ملفات Typst، بما في ذلك العناوين التوضيحية وخلايا الجداول وحقول القوالب مثل `abstract:`، ويتخطى الأكواد. ويفحص [Preflight](/docs/preflight/#typst-projects) مصادر Typst بحثًا عن مراجع واستشهادات غير محلولة ونص بديل مفقود وصور مفقودة وبيانات وصفية للمستند ومشكلات تحكيم مجهول.

## الانتقال بين المصدر وملف PDF

اختر **Go to PDF** من شريط الأدوات أو اضغط ⌘⇧J / Ctrl+Shift+J للانتقال من المؤشر إلى الصفحة. وفي ملف PDF، اضغط ⌘ أو Ctrl باستمرار وانقر كلمة للعودة إلى سطرها، ولو في ملف أُدخل بـ`#include`. تحتاج المزامنة إلى Typst 0.13 أو أحدث. انظر [مزامنة المصدر مع PDF](/docs/synctex/#typst-projects).

## تنسيق الملف

يرتِّب **Format document** الملف كله باستخدام typstyle. اضغط ⇧⌥F / Shift+Alt+F أو اختره من قائمة النقر بالزر الأيمن. أما **Format selection** فينسِّق الأسطر المحددة فقط. وللتنسيق في كل مرة تضغط فيها ⌘S / Ctrl+S، فعِّل **Format on save** ضمن **Typst** في **Settings → Appearance → Editor**. انظر [تنسيق ملف Typst](/docs/code-intelligence/#format-a-typst-file).

## نسخ Typst

يأتي Oleafly مع Typst 0.15.1، وتعرض **Settings → Engines → Typst** نسخ Typst من 0.11 إلى 0.15 للتنزيل. المشروع الجديد يثبِّت النسخة الافتراضية، فتبقى فواصل الأسطر وعدد الصفحات على حالهما حين يصدر Oleafly لاحقًا نسخة Typst أحدث. ولتغيير نسخة مشروع واحد، افتح السهم المجاور لـ**Recompile** واختر تحت **Typst version (this project)**. يتبع خادم اللغة نسخة المشروع. ويشرح [نسخ Typst](/docs/typst/#typst-versions) التثبيت والنسخ المفقودة وكيفية تجربة إصدار أحدث قبل التبديل.

## التنظيم والتصدير

قسِّم التقرير الطويل إلى ملفات وأدخلها بـ`#include "sections/method.typ"`. أبقِ ملفات الأشكال والبيانات والخطوط وقوائم المراجع داخل المشروع لينتقل ملف ZIP للمصدر بكل ما يحتاجه المستند.

جمِّع للتحقق من النتيجة، ثم افتح **Export**. يقدم **Export as PDF** و**Export source (.zip)** و**Export page as PNG** و**Images and HTML**، الذي يكتب صفحات PNG أو SVG أو ملف HTML بـTypst نفسه. وفي Typst 0.13 وما بعده، تمر تصديرات Word وHTML وMarkdown وLaTeX والنص العادي عبر مخرجات HTML الخاصة بـTypst، فتنجو المعادلات والمراجع. انظر [تصدير المشروع وتحويله](/docs/export/#typst-images-and-html). ويشرح [التجميع](/docs/compiling/) السجلات وخيارات التجميع، ويغطي [الملفات والمجلدات](/docs/files/) تنظيم المشاريع.

لنقل مشروع LaTeX قائم إلى Typst، انظر [تحويل مشروع LaTeX إلى Typst](/docs/typst/#convert-a-latex-project-to-typst).