# الكتابة في Markdown

سوِّد بترميز Markdown المألوف وأنتج ملف PDF أو مستندًا قابلًا للتحرير للمتعاونين.

يعمل Markdown جيدًا لملاحظات البحث والتقارير والمسودات المبكرة. يوفر له Oleafly شريط تنسيق مخصصًا ومسار بناء عبر Pandoc، مع ملفات مصدر يمكنك استخدامها خارج التطبيق.

## إنشاء تقرير

1. اختر **New project → Use a template → Blank Markdown document**.
2. سمِّ المشروع **ملاحظات ميدانية** وافتح `main.md`.
3. الصق هذا المثال، ثم اختر **Recompile** أو اضغط **⌘Enter / Ctrl+Enter**.
4. إذا عرض Oleafly إعداد محرك لازم، فأكمل ذلك الإعداد ثم جمِّع مرة أخرى.

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

ينبغي أن يتضمن ملف PDF عنوانًا وعناوين وقائمة مرقمة وجدولًا. تتحكم البيانات الوصفية الواقعة بين أول زوج من أسطر `---` في عنوان المستند ومؤلفه.

## أنواع المستندات

أضف سطر `type` إلى الواجهة الأمامية لبناء المستند كتقرير أو كتاب أو شرائح أو ملصق أو خطاب أو سيرة ذاتية. وبدون `type`، أو بقيمة لا يعرفها Oleafly، يُبنى المستند كمقال.

| `type` | ما يبنيه | ما يُملأ ما لم تضبطه |
| --- | --- | --- |
| `article` | مقال | لا شيء |
| `report` أو `thesis` | تقرير، بفصل عند كل عنوان `#` | `documentclass: report` |
| `book` | كتاب، بفصل عند كل عنوان `#` | `documentclass: book` |
| `slides` | شرائح Beamer بنسبة 16:9. يبدأ العنوان `#` قسمًا ويبدأ العنوان `##` شريحة | `aspectratio: 169` |
| `poster` | ملصق Beamer من صفحة واحدة، يتصدره `title` و`subtitle` و`author` و`institute` | ورق A0، بالاتجاه العمودي |
| `letter` | خطاب بعنوانك وعنوان المستلم، وسطر موضوع، وتحية افتتاحية، وخاتمة | `documentclass: scrlttr2` |
| `cv` | مقال مضغوط | `geometry: margin=2cm` و`pagestyle: empty` |

تبقى الواجهة الأمامية التي كتبتها أنت هي صاحبة الأولوية. فأي قيمة تضبطها بنفسك، مثل `documentclass` أو `aspectratio` أو `geometry`، تحل محل القيمة التي يملؤها النوع.

للشرائح، اضبط `slide-level` لاختيار مستوى العنوان الذي يبدأ شريحة. ومع `slide-level: 1`، يبدأ كل عنوان `#` شريحة. وتُبنى الشرائح كملف PDF عادي، لذا يستطيع **Present** في شريط أدوات المعاينة عرضها. راجع [عرض الشرائح](/docs/present-slides/).

يكون الملصق بحجم A0 ما لم تضبط `papersize` على `a1` أو `a2` أو `a3` أو `a4`. وتُتجاهل الأحجام الأخرى، مثل `letter` أو `a5`. أضف `orientation: landscape` لملصق عريض.

يأخذ الخطاب عنوان المستلم من `to` وعنوانك من `from`. ويكون `opening` التحية الافتتاحية، ويكون `closing` السطر الذي يسبق اسمك، وهو يأتي من `author`. ويصبح `subject` سطر الموضوع، أو `title` إن لم يوجد `subject`. اكتب العنوان كقائمة، بسطر واحد لكل عنصر.

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

يكتب **Document type** في [Document settings](/docs/document-settings/#markdown) سطر `type` عنك. ويتبع [تصدير LaTeX](/docs/export/#what-each-format-keeps) النوع أيضًا، ويستخدم [تصدير PowerPoint](/docs/export/#presentation-and-book-exports) للشرائح قيمة `slide-level` نفسها. ويبني [`oleafly build`](/docs/cli/#build-a-project) كل نوع بالطريقة نفسها التي يعمل بها التطبيق.

## التحرير بالمصدر والتحرير المرئي

لمفتاح بداية شريط الأدوات ثلاثة أوضاع. يحرر **Code** ترميز Markdown مباشرة. ويمنح **Visual** تحريرًا منسقًا للعناوين والفقرات والقوائم والروابط والصور والجداول. ويعرض **Both** المصدر والنص المنسق معًا. افتح قائمته لاختيار **Stacked** أو **Split**. تُفتح المشاريع الجديدة في وضع Code، ويتذكر كل مشروع الوضع الذي تركته عليه.

التسطير والتمييز والرمز المرتفع والرمز المنخفض عناصر تنسيق من Pandoc في وضع Code. تكون أزرارها مخفية في وضع Visual. استخدم Code عند العمل على البيانات الوصفية أو صياغة الاستشهادات أو غيرها من مكوّنات المصدر.

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

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

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

### Code / Visual

بدّل بين **Code** و**Visual** و**Both**. يبقى المستند مصدر Markdown في كل وضع.

### Undo

يتراجع عن آخر تعديل. ⌘Z / Ctrl+Z.

### Redo

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

### Heading → Title

اختر **Title** من قائمة العناوين لإدراج `# Title`. استبدل نص العنوان بعنوانك الخاص.

### Heading → Section

اختر **Section** من قائمة العناوين لإدراج `## Section`. استبدل نص العنوان بعنوانك الخاص.

### Heading → Subsection

اختر **Subsection** من قائمة العناوين لإدراج `### Subsection`. استبدل نص العنوان بعنوانك الخاص.

### Heading → Subsubsection

اختر **Subsubsection** من قائمة العناوين لإدراج `#### Subsubsection`. استبدل نص العنوان بعنوانك الخاص.

### Heading → Minor heading

اختر **Minor heading** من قائمة العناوين لإدراج `##### Minor heading`. استبدل نص العنوان بعنوانك الخاص.

### Heading → Paragraph heading

اختر **Paragraph heading** من قائمة العناوين لإدراج `###### Paragraph heading`. استبدل نص العنوان بعنوانك الخاص.

### Bulleted list

يبدأ قائمة غير مرتبة. `- Item`.

### Numbered list

يبدأ تسلسلًا. `1. Item`.

### Task list

في وضع Code، أضف مهمة وغيّر `[ ]` إلى `[x]` عند إكمالها. `- [ ] Task`.

### Blockquote

ضع اقتباسًا في سطر مستقل. `> quoted text`.

### Bold

يبرز النص المحدد. `**text**`؛ ⌘B / Ctrl+B.

### Italic

يبرز مصطلحًا. `*text*`؛ ⌘I / Ctrl+I.

### Strikethrough

يميز نصًا لم يعد معتمدًا. `~~text~~`.

### Inline code

ينسّق اسم ملف أو أمرًا أو معرّفًا. نص محاط بعلامات backticks.

### Underline

حدِّد عبارة في وضع Code. `[text]{.underline}`.

### Highlight

حدِّد عبارة في وضع Code. `[text]{.mark}`.

### Superscript

حدِّد الأس في وضع Code. `^text^`.

### Subscript

حدِّد الرمز المنخفض في وضع Code. `~text~`.

يستخدم التسطير والتمييز خصائص Pandoc حتى ينتقل التنسيق إلى ملف PDF. استخدم هذين العنصرين بدلًا من إضافة وسوم HTML خام إلى المخطوطة.

### Insert link

في وضع **Code**: يُدرج `[link text](url)`. استبدل العنصرين النائبين.

في وضع **Visual**: يفتح **Link URL**. أدخل العنوان وطبّقه على تحديدك. استخدم **Remove link** للاحتفاظ بالنص دون الرابط.

### Insert image

في وضع **Code**: يُدرج `![caption](image-filename)`. استبدل المسار والتعليق.

في وضع **Visual**: يفتح **Image file**. أدخل مسارًا في المشروع مثل `figures/plot.png` وطبّقه.

تدخل صور PNG وJPG وPDF وSVG وGIF وWebP وBMP كلها في ملف PDF. ويحوّل Oleafly صور SVG وGIF وWebP عنك عند التجميع. أما صور TIFF وAVIF وHEIC وJPEG XL فلا يمكن إدخالها: يتوقف التجميع ويسمّي الملف، فاحفظه بإحدى الصيغ الأخرى وجمّع مرة أخرى. وإذا فشل التحويل، فتحقق من أن الصورة تُفتح، أو احفظها بصيغة PNG أو PDF.

### Insert table

في وضع **Code**: يُدرج ثلاثة أعمدة وصف ترويسة وصفَي بيانات. استبدل أسماء الأعمدة والخلايا.

في وضع **Visual**: يُدرج جدولًا قابلًا للتحرير بالأبعاد الابتدائية نفسها.

### Draw a diagram

يفتح [محرر المخططات](/docs/figures-diagrams/) في وضع Mermaid. ارسم مخطط تدفق على اللوحة أو حرّر شيفرة Mermaid، ثم اختر **Insert as Mermaid** لإضافته عند المؤشر ككتلة شيفرة `mermaid` مسوّرة. انظر [مخططات Mermaid](#mermaid-diagrams).

### Document insights

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

### Document settings

يغيّر نوع المستند وصنف المستند وحجم الورق والأعمدة والهوامش وخط المتن وحجم الخط واللغة والتباعد بين الأسطر وترقيم الأقسام. يكتب Oleafy اختياراتك في بيانات front matter بصيغة YAML التي يقرؤها Pandoc، ويضيف كتلة بيانات وصفية إن لم يكن في الملف أي منها. انظر [إعدادات المستند](/docs/document-settings/#markdown).

### Project info

في وضع **Code**: يعرض إحصاءات المشروع ومعلومات التحديد.

في وضع **Visual**: يعرض إحصاءات سطح التحرير المرئي.

### Find

في وضع **Code**: يفتح بحث الملف النشط عبر ⌘F / Ctrl+F.

في وضع **Visual**: يكون زر Find في شريط المصدر مخفيًا.

استورد الصورة عبر شجرة الملفات قبل الإشارة إليها. أبقِ مسارات الصور نسبية إلى المخطوطة حتى يعمل أرشيف المصدر على حاسوب آخر.

![دفتر مختبر بصيغة Markdown يُحرَّر في عرضَي المصدر والعرض المرئي، ويبقى الجدول وقائمة المهام متزامنين.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## المعادلات وكتل الشيفرة

اكتب الرياضيات السطرية بصيغة `$x^2$`. وضع معادلة العرض بين زوجين من علامتي الدولار:

```markdown
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
```

للحصول على نموذج شيفرة، ضع الشيفرة بين ثلاث علامات backticks واذكر لغتها بعد العلامة الافتتاحية. هذان مكوّنان من مكوّنات المصدر؛ وليس في شريط أدوات Markdown زر منفصل للمعادلات أو لكتل الشيفرة المسوّرة.

في وضع **Visual**، تبقى الكتلة المسوّرة كتلة شيفرة وتحتفظ بلغتها وأسطرها الفارغة، فتنجو مخططات Mermaid. اكتب ثلاث علامات backticks لبدء كتلة جديدة، واضغط Tab للإزاحة داخل كتلة.

## مخططات Mermaid

اختر **Draw a diagram** في شريط الأدوات لإنشاء مخطط تدفق Mermaid في محرر المخططات. يضيف **Insert as Mermaid** المخطط ككتلة شيفرة مسوّرة:

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

في وضع **Both**، يرسم الجانب المنسق الكتلة مخططًا. ويحتاج ملف PDF إلى صورة، لذا يحفظ محرر المخططات أيضًا صورة PNG مرسومة في `figures/mermaid-<hash>.png`، وتضع عملية التجميع تلك الصورة مكان الكتلة. لذلك يظهر المخطط في ملف PDF المجمَّع أيضًا، وفي تصديرات Word وHTML وEPUB وPowerPoint. وإذا حرّرت الكتلة يدويًا بعد ذلك، فسيعرض ملف PDF الشيفرة إلى أن تُدرج المخطط من محرر المخططات من جديد أو تحفظه منه مرة أخرى. انظر [Mermaid في مستندات Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## النص بلغات أخرى

يختار Oleafly الخطوط لأنظمة الكتابة التي يجدها في المستند، فتظهر الكورية واليابانية والصينية والعربية والعبرية واليونانية والسيريلية والديفاناغاري والتايلاندية وعدة أنظمة كتابة أخرى دون أي إعداد. وتحصل الرموز والإيموجي على خط أيضًا، والإيموجي بالأبيض والأسود. والمستند المكتوب في معظمه بالعربية أو العبرية يسير من اليمين إلى اليسار.

تظهر الأحرف الصينية في النص الصيني والياباني معًا، فاضبط `lang` في مقدمة الملف لتحصل على الخط الصحيح: `ja` لليابانية، و`zh` للصينية المبسطة، و`zh-TW` للصينية التقليدية، أو `ko` للكورية. ودون `lang`، يعتمد Oleafly على النص: الكانا تعني اليابانية والهانغول تعني الكورية.

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

الخطوط التي تختارها بنفسك تأتي أولًا. وحين تضبط مقدمة الملف `mainfont` أو `CJKmainfont`، أو يعدّ `header-includes` الخطوط، يترك Oleafly ذلك الجزء وشأنه.

### أحرف مفقودة من ملف PDF

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

- للنص الكوري أو الصيني أو الياباني، اضبط `CJKmainfont` في مقدمة الملف على خط مثبّت على حاسوبك يحوي الأحرف.
- للنص الآخر، اضبط `mainfont` بالطريقة نفسها. ويكتبه لك **Body font** في [Document settings](/docs/document-settings/#markdown).
- للرمز النادر، استخدم صورة بدلًا منه.

## الاستشهادات وقائمة المراجع

استورد ملف `references.bib` أو أنشئه، وأضف `bibliography: references.bib` إلى البيانات الوصفية بصيغة YAML، واستشهد بمفتاح موجود بـ `[@citation-key]`. يستخدم Pandoc قائمة المراجع لإنتاج استشهادات منسقة وقائمة مراجع.

إذا لم تسمِّ المقدمة قائمة مراجع، أو سمّت ملفًا غير موجود، يستخدم التجميع ملفات `.bib` في المشروع التي تحوي المفاتيح التي تستشهد بها. والاستشهاد الذي لا قائمة مراجع له أصلًا يبقى في ملف PDF كما كتبته، مثل `[@smith2020]`، فتستطيع الكتابة أولًا وإضافة المراجع لاحقًا. والمستند الذي لا يستشهد بشيء يُبنى دون قراءة أي ملف `.bib`.

[ابحث عن المراجع وأدرها →](/docs/citations/)

## الاستيراد والتصدير

للاحتفاظ بمسودة موجودة بترميز Markdown، أنشئ مستند Blank Markdown، والصق المسودة في `main.md`، ثم استورد صورها وقائمة مراجعها. أما استيراد **Markdown document** المنفصل في المكتبة فيحوّل المسودة حاليًا إلى LaTeX. يشرح [مسارات الاستيراد](/docs/import-project/) المسارين.

جمِّع للحصول على PDF، أو استخدم **Export** لإنشاء Word أو HTML أو Typst أو LaTeX أو PowerPoint أو EPUB أو نص عادي. والتصديرات إلى LaTeX وTypst تحتفظ بقائمة المراجع، وتشير إلى ملفات صورك بدلًا من نسخها، لذا أبقِ تلك الملفات بجانب الملف المصدَّر. وحين يترك Pandoc شيئًا، يُحفظ التصدير بتحذيرات، ويسرد **Show warnings** ما أُسقط. واستخدم ملف ZIP للمصدر لمشاركة Markdown الأصل وأصوله. يغطي [تصدير عملك](/docs/export/) التسلسل والفحوص التي تجريها في الملف المحوّل.
