# صيغة المستند

> مجموعة Markdown الجزئية التي يحلّلها Postext، وقواعد كتابة المستندات المصدرية

- نسخة HTML: https://postext.dev/ar/docs/document-format
- آخر تحديث: 2026-09-29
- مدة القراءة: 10 دقائق
- لغات أخرى: [en](https://postext.dev/en/docs/document-format.md), [es](https://postext.dev/es/docs/document-format.md), [ca](https://postext.dev/ca/docs/document-format.md), [zh](https://postext.dev/zh/docs/document-format.md)

## باختصار

تشرح هذه الصفحة كيف تكتب نصًا يستطيع Postext أن يُخرجه في صفحات. تكتب بلغة Markdown، وهي طريقة بسيطة في الكتابة تدلّ فيها رموز قليلة على العناوين والقوائم والكلمات الغامقة والروابط. ويفهم Postext أيضًا علامات إضافية للإطارات والحواشي والصور والجداول والمعادلات. تسرد الصفحة كل علامة يقبلها وكل علامة يتجاهلها، وتنتهي بنصائح لكتابة نص سهل القراءة.

**يقرأ Postext لهجة Markdown صغيرة عن قصد.**

المحلّل مُقطِّع (tokenizer) مكتوب يدويًا، لا تطبيق كامل لمواصفة CommonMark، ولذلك فصيغة المصدر ضيقة ويمكن توقّع سلوكها. والغاية من ذلك أمران: أن يبقى المحرّك صغيرًا وسريعًا، وأن تنتقل المستندات بلا عناء بين Postext وأي قارئ آخر لـ CommonMark (Obsidian وPandoc وVS Code…). كل ما لا تذكره هذه الصفحة إما يُعامل نصًا عاديًا وإما يُحذف من التدفق السطري.

إذا كنت تبني مستندًا برمجيًا، فالدالة `parseMarkdown` (انظر [الإعدادات › التحليل](/ar/docs/configuration#التحليل)) تعطيك بنية الكتل نفسها التي يستهلكها محرّك الإخراج.

## البيانات التمهيدية (frontmatter)

يجوز أن يبدأ المستند بكتلة بيانات تمهيدية اختيارية بصيغة YAML محاطة بعلامتَي `---`:

```md
---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---

# Chapter One

The story begins here…
```

استدعِ `extractFrontmatter(source)` لفصل البيانات التمهيدية عن المتن. يُعاد كائن البيانات الوصفية المحلَّل مع ما بقي من Markdown ومع موضع الحرف الذي يبدأ عنده المتن، وهذا مفيد إذا احتجت إلى ردّ الأخطاء أو مواضع المؤشر إلى المصدر الأصلي.

تُحلَّل البيانات التمهيدية بمكتبة [`gray-matter`](https://github.com/jonschlinkert/gray-matter)، فتُقبل أي بنية YAML. لا ينظر Postext نفسه إلا إلى `title` و`subtitle` و`author` و`publishDate`؛ أما المفاتيح الأخرى فتُحفظ في `PostextContent.metadata` وتستخدمها كما تشاء.

تعطي YAML قيمها أنواعًا: `1984` عدد، و`2026-04-15` تاريخ، و`[Ana Gil, Luis Paz]` قائمة. يطبع Postext كل حقل من هذه الحقول الأربعة نصًا أيًّا كان نوعه:

- العدد بصيغته العشرية البسيطة، والقيمة المنطقية `true` أو `false` (`title: 1984` يطبع *1984*). تقرأ YAML العدد قيمةً لا رقمًا رقمًا: `1.50` يطبع *1.5*، و`017` (ثماني) يطبع *15*، و`1:30` (بالأساس 60) يطبع *90*؛
- التاريخ بيومه في التقويم، مكتوبًا بلغة المستند، أي الإعداد `locale`، وإلا فلغة تقسيم الكلمات: `publishDate: 2026-04-15` يطبع *April 15, 2026* بالإنجليزية، و*15 de abril de 2026* بالإسبانية، و*15. April 2026* بالألمانية. وتستخدم التواريخ العربية التقويم الميلادي ما لم يسمِّ الوسم تقويمًا آخر (`ar-u-ca-islamic` يطبع التاريخ الهجري)، بالأرقام التي يقتضيها الوسم (`ar-EG`: ١٥ أبريل ٢٠٢٦؛ `ar-u-nu-latn`: 15 أبريل 2026). والتاريخ الذي يحمل وقتًا من اليوم يطبع يوم وقته بتوقيت UTC ويُسقط الوقت: `2026-09-24T23:30:00-05:00` هو الساعة 04:30 بتوقيت UTC من يوم 25، فيطبع *September 25, 2026*؛
- القائمة بعناصرها مفصولة بفواصل (`author: [Ana Gil, Luis Paz]` يطبع *Ana Gil, Luis Paz*).

ضع القيمة بين علامتَي تنصيص لتُطبع كما كُتبت تمامًا، كعدد يجب أن يحتفظ بأرقامه أو تاريخ يجب أن يحتفظ بيومه: `publishDate: "15/04/2026"`، `title: "1984"`. يصل النص إلى `doc.metadata` وإلى العناصر النائبة (`{title}`، `{publishDate}`…) وإلى عنوان ملف PDF ومؤلفه. وأي حقل من الحقول الأربعة لا صيغة نصية له، كخريطة متداخلة أو `title:` فارغ، يُترك خارج `doc.metadata`. وتظل `extractFrontmatter` تعيد القيم بالأنواع التي أعطتها إياها YAML؛ أما `metadataText(value, locale)` فتعطي النص الذي يطبعه Postext لإحداها.

## البنى الكتلية

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

> **شكل: بنى كتل النص في لمحة**
> أنواع كتل النص السبعة التي يتعرّف عليها Postext: العنوان والفقرة والاقتباس الكتلي والقائمة غير المرقّمة والقائمة المرقّمة وقائمة المهام والمعادلة المستقلة، ولكل منها صياغته في Markdown. أما التوجيهات وتضمين الموارد فمشروحة على حدة.
>
> *كل نوع من كتل النص ومدخله في Markdown.*

| البنية | الصياغة | ملاحظات |
| --- | --- | --- |
| عنوان | `# Title` … `###### H6` | من علامة `#` واحدة إلى ست علامات، تليها مسافة ثم نص العنوان. تقابل المستويات 1–6 مباشرة الإعداد `headings.levels`. |
| فقرة | نص عادي على سطر واحد أو أكثر | تُضمّ الأسطر المتتالية غير الفارغة وغير الخاصة بمسافة واحدة وتخرج فقرة واحدة. وبين حرفين صينيين أو يابانيين (الحروف الإيديوغرافية والكانا وعلامات الترقيم كاملة العرض، وعلامات التنصيص المنحنية والشرطات وعلامة الحذف المجاورة لها) تُحذف نهاية السطر بدلًا من ذلك، كما تفعل CSS، فيجوز لف الفقرة الصينية في أي موضع من المصدر. وبين علامتين من هذا النوع (`“你好”⏎“再见”`، `他说……⏎“好”`) يحسم الأمر الحرفان الواقعان بعدهما: تُحذف نهاية السطر إذا كان أحدهما صينيًا أو يابانيًا، أما `“hello”⏎“bye”` فتحتفظ بمسافتها. وتحتفظ الكورية بمسافتها. لا تُحفظ فواصل الأسطر اليدوية داخل الفقرة؛ استخدم سطرًا فارغًا لبدء فقرة جديدة. |
| اقتباس كتلي | `> quoted text` | يجب أن يبدأ كل سطر من الاقتباس بالعلامة `>` (تليها مسافة اختيارية واحدة). تندمج أسطر الاقتباس المتتالية في كتلة اقتباس واحدة، وتُضمّ كما تُضمّ أسطر الفقرة. ويُنضَّد كما يقول `bodyText.blockquote`: بحروف مائلة رمادية مع إزاحة السطر الأول في المتن ما لم تغيّرها (انظر [الإعدادات › الاقتباسات الكتلية](/ar/docs/configuration#الاقتباسات-الكتلية)). |
| قائمة غير مرقّمة | `- item`، `* item`، `+ item` | تُقبل أي علامة من علامات التنقيط الثلاث. يكون التداخل **بمسافتين بالضبط لكل مستوى**، حتى عمق أقصى قدره 5. |
| قائمة مرقّمة | `1. item`، `2) item` | أرقام تليها `.` أو `)`. يُحفظ رقم البداية (فيمكن أن تبدأ القائمة من 5 أو من 0). أما الفاصل الذي يظهر في المخرجات فيأتي من `orderedLists.separator` لا من المصدر. |
| قائمة مهام (GFM) | `- [ ] todo`، `- [x] done` | عنصر غير مرقّم بمربع اختيار بين قوسين معقوفين. يقبل `x` الصغيرة أو `X` الكبيرة. ويُرسم بالرمزين `taskCheckboxChar` / `taskCheckedChar`. |
| معادلة مستقلة | `$$ … $$` | معادلة LaTeX تُنضَّد كتلةً قائمة بذاتها. تُرسم في وسط العمود، وتُلحَق بشبكة خطوط الأساس كما يُلحَق العنوان، وتبقى متجهية في مخرجات PDF. والصيغتان، ذات السطر الواحد والمسيّجة متعددة الأسطر، مشروحتان في [المعادلات الرياضية](https://postext.dev/ar/docs/document-format#الصيغ-الرياضية). |

يُحتمل سطر فارغ واحد بين عنصرين من القائمة، فتبقى القائمة متصلة. أما سطران فارغان أو أكثر فينهيان القائمة.

تُقبل القوائم المختلطة الأنواع في العمق نفسه (يمكنك التحول من غير المرقّمة إلى المرقّمة في منتصف السلسلة)، لكن المحرّك يعامل كل سلسلة على حدة في الترقيم. وعمليًا، احتفظ بنوع واحد لكل عمق ما لم يكن لديك سبب للخلط.

> **شكل: عمق تداخل القوائم**
> تتداخل القوائم بمسافتين بالضبط لكل مستوى، حتى عمق أقصى قدره خمسة. يزيد كل مستوى الإزاحة ويجوز أن يستخدم نمط تنقيط مختلفًا.
>
> *مسافتان لكل مستوى. العمق الأقصى: خمسة.*

### سمات العناوين

يجوز أن ينتهي سطر العنوان بكتلة سمات بين قوسين معقوصين، بصياغة `key="value"` نفسها التي تستخدمها التوجيهات:

```markdown
# The Long Road {author="I. Zango Martín" year=1998}
```

تُحذف الأقواس ومحتواها من نص العنوان (فالعنوان أعلاه يُرسم *The Long Road*) وتُخزَّن على العنوان باسم `attrs`. وتُتاح لخانات التصميم عناصرَ نائبة بصيغة `{attr.<key>}`: في خانة التصميم المتقدم الخاصة بالعنوان نفسه، وفي ترويسات الصفحات وتذييلاتها، حيث تُستمد قيمها من عنوان H1 للفصل الحالي. ولا يُتعرَّف إلا على كتلة متوازنة خالية من الأقواس في آخر السطر تمامًا، بعد مسافة، أو مباشرة بعد حرف صيني أو ياباني لأن العناوين الصينية تُكتب بلا مسافة (`# 回目{style="x"}`). ولا تؤخذ الكتلة إلا إذا قرأتها صياغة السمات المشروحة أدناه كلها: فـ`{x, y}` و`{紅樓|hóng lóu}` و`{}` المنفردة تبقى في العنوان، وكذلك الرايات المنفردة الملتصقة بالعنوان (`# 第一回{draft}`). تُفصل السمات بمسافات، فالكتلة التي فيها فواصل (`{a="1", b="2"}`) وصيغة Pandoc `{.class}` تبقيان في العنوان أيضًا. أما معرّف Pandoc `{#id}` فيُقرأ: هو نفسه `id="…"` ويسمّي العنوان لأجل [الإحالات المرجعية](#الإحالات-والمراسي). والمفتاح المكتوب بنظام كتابة آخر يُقرأ ويُسقط مع تحذير (انظر أدناه)، فـ`# 回目{style="x" 作者=曹雪芹}` تأخذ `style` مع ذلك. انظر **الإعدادات › الترويسات والتذييلات**.

يجوز أن تمتد القيمة التي يطبعها نص في التصميم على عدة أسطر: الحرفان `\n` يبدآن سطرًا جديدًا في موضعهما، أيًّا كانت قيمة `overflow` للعنصر (`to="Firma X\nStrasse 1\n10115 Berlin"` يطبع عنوانًا بريديًا من ثلاثة أسطر). ومع `inlineMarks` على العنصر تُطبَّق العلامات السطرية في القيمة أيضًا: `authors="Ana Ruiz^1^, Luis Gil^2^"` ينضّد أرقام الانتساب حروفًا علوية. وهذا التهريب خاص بقيم السمات (وبقوالب التصميم نفسها): الحرفان `\n` في نص العنوان، داخل مقطع شيفرة مثلًا، يُطبعان كما كُتبا.

لسمتين معنى خاص بهما. `style="<id>"` تطبّق على العنوان [نمط عنوان](/ar/docs/configuration#أنماط-العناوين) مسمّى: مقدمة أو قائمة مؤلفين لها تصميم افتتاح خاص وترويسات وهندسة صفحة وطباعة متن خاصة بها، وبلا رقم فصل إذا قال النمط `numbered: false`. و`toc="false"` (أو `"true"`) تحدد ما إذا كان `:::toc` يُدرج العنوان:

```markdown
# Preface {style="front-matter"}

# Contents {style="front-matter" toc="false"}
```

وسمتان أخريان تغيّران ما يطبعه العنوان وكيف يُعدّ. `hidden="true"` (أو `"false"`) تتجاوز قيمة `hidden` لمستوى العنوان أو نمطه: العنوان المخفي لا يطبع شيئًا ولا يشغل مكانًا، في التدفق وداخل إطار `:::callout` على السواء، لكنه يظل يفتح صفحته ويُعدّ ويُدرج في المحتويات وفي ترويسات `{chapterTitle}` وفي إشارات PDF المرجعية. و`startAt=N`، وهو عدد صحيح موجب، يضبط عدّاد مستوى العنوان على `N` بدلًا من زيادته؛ وتواصل العناوين التالية العدّ من هناك، في الفصول اللاحقة أيضًا، وتبدأ المستويات الأدنى من جديد تحته كالمعتاد. ومع نمط عنوان يرقّم الملاحق بالحروف (`numberingTemplate: 'Appendix {1:A}'`)، يعيد الملحق الأول بدء العدّ ليُقرأ *Appendix A* بدلًا من متابعة العدّ من الفصول:

```markdown
# To my mother {hidden="true" toc="false"}

# Survey instrument {style="appendix" startAt=1}

# Raw data {style="appendix"}
```

## التوجيهات

التوجيهات وسوم تحكّم من سطر واحد تُكتب بصيغة `:::name` أو `:::name{attrs}` في سطر مستقل. لا تُنتج مخرجات مرئية، بل توجّه مسار التموضع والترقيم.

| الصياغة | الأثر |
| --- | --- |
| `:::pagebreak` | يجبر الكتلة التالية على البدء في صفحة جديدة. |
| `:::pagebreak{parity="odd"}` | مثله، مع ضمان أن تكون الصفحة الجديدة فردية (اليمنى في الكتاب اللاتيني). ويُدرج صفحة حشو فارغة عند الحاجة. |
| `:::pagebreak{parity="even"}` | مثله، لكن الهدف صفحة زوجية (اليسرى في الكتاب اللاتيني). |
| `:::pagebreak{parity="always-odd"}` | يضمن صفحة فاصلة فارغة إلزامية واحدة على الأقل قبل الوصول إلى صفحة فردية. تتبع الصفحة الفارغة الفاصلة المحتوى السابق؛ وأي حشو إضافي للزوجية يتبع ما يليه. مفيد حين يجب أن يبدأ كل فصل في صفحتين متقابلتين جديدتين. |
| `:::pagebreak{parity="always-even"}` | مثله، لكن الهدف صفحة زوجية. |
| `:::numbering{format="decimal" startAt=1}` | يبدّل سلسلة ترقيم الصفحات عند حدّ الصفحة التالي. السمتان اختياريتان: احذف `format` لإبقاء الصيغة، واحذف `startAt` لمتابعة العدّاد. |
| `:::columnbreak` | ينهي العمود الحالي هنا: تبدأ الكتلة التالية في العمود التالي من الصفحة نفسها (أو في صفحة جديدة إذا وقع التوجيه في العمود الأخير). لا يفعل شيئًا في عمود فارغ، فلا يُنتج أبدًا عمودًا أو صفحة فارغة. ويحتفظ العمود الذي ينهيه بفراغه السفلي، فلا تمدّه موازنة الأعمدة. |
| `:::space` | يترك هنا سطر متن فارغًا واحدًا، وهي الطريقة الصريحة لإضافة شيء من الفسحة بين كتلتين. `:::space{lines=2}` يترك سطرين (والكسور مثل `0.5` تعمل أيضًا). يُضاف إلى الهامش القائم بين الكتلتين ويُسقط في أعلى العمود أو الصفحة. انظر [أدناه](https://postext.dev/ar/docs/document-format#space). |
| `:::toc` | يطبع جدول المحتويات هنا: مدخل لكل عنوان من المستويات المدرجة (العنوان والرقم ورقم الصفحة ومؤلفو الفصل اختياريًا) وصف لكل فاصل جزء، منضّدة وفق إعداد `toc`. تتبع المداخل المستند: أعد تسمية فصل أو انقله أو أعد ترقيمه فتتبعه المحتويات. |
| `:::index` | يطبع هنا الفهرس الأبجدي (index) في آخر الكتاب: كل مصطلح معلَّم بـ`:index` في الكتاب، مرتبًا ومجمّعًا حسب الحرف، مع الصفحات التي يقع فيها، منضّدًا وفق إعداد `index`. و`:::index{index="names"}` يطبع فهرسًا مسمّى. انظر [الفهرس الأبجدي](https://postext.dev/ar/docs/document-format#الفهرس-الأبجدي). |
| `:::verse` … `:::` | قصيدة بالتخطيط العربي الكلاسيكي: بيت في كل سطر، وشطراه مفصولان بـ`\|\|`، ويُنضَّدان جنبًا إلى جنب بعرض مشترك واحد. انظر [أدناه](https://postext.dev/ar/docs/document-format#verse). |

يجوز أن تكون قيم السمات بين علامتَي تنصيص مزدوجتين (<code>"…"</code>) أو مفردتين (<code>'…'</code>) أو مجرّدة (<code>startAt=17</code>). والمفتاح المجرّد بلا `=` يُعامل راية حاضرة لكنها فارغة.

لا يُتعرَّف اليوم توجيهاتٍ من سطر واحد إلا على `pagebreak` و`numbering` و`columnbreak` و`space` و`toc` و`index` (وعلى `references` و`verse` كتلًا مسيّجة)؛ وأي سطر `:::name` آخر ليس حاوية (انظر أدناه) يُحلَّل فقرةً ويُظهر تحذير **توجيه غير معروف** (Unknown directive) في Sandbox. ويسجّله المحرّك أيضًا مدخلًا من نوع `unknownDirective` في `contentWarnings` الخاصة بالمستند (انظر [الإعدادات › التحذيرات في المستند](/ar/docs/configuration#التحذيرات-في-المستند)).

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

صياغة `key="value"` نفسها تقرؤها سمات العناوين، وأسوار التوجيهات والحاويات (`:::name{…}`)، والإحالات السطرية (`:ref{…}`)، والشارات (`:chip[…]{…}`)، وعيّنات الألوان (`:swatch{…}`)، وعلامات الفهرس (`:index[…]{…}`). وقواعدها:

- **المفاتيح** تبدأ بحرف ASCII أو `_` وتستمر بحروف ASCII أو أرقام أو `_` أو `-`. المسافات حول `=` مقبولة، وعلامة `＝` كاملة العرض التي تكتبها طريقة الإدخال الصينية تعمل عمل `=`، والمفتاح المكرر يحتفظ بآخر قيمة له، والمفتاح بلا `=` راية بقيمة فارغة. والمفتاح المكتوب بنظام كتابة آخر (`作者=曹雪芹`) لا يُقرأ ويُطلق تحذير `attributeKeyInvalid`؛ وتظل مفاتيح الكتلة الأخرى سارية. أما القيم فيجوز أن تكون بأي نظام كتابة.
- **القيم بين علامتَي تنصيص.** القيمة بين علامتين مزدوجتين تتسع لأي شيء عدا `"`، بما في ذلك العلامات المفردة؛ والقيمة بين علامتين مفردتين تتسع لأي شيء عدا `'`. فالقيمة التي فيها علامات تنصيص مزدوجة توضع بين علامتين مفردتين: `lead='He said "hi"'`. لا توجد تهريبات، فالشرطة المائلة العكسية حرف عادي، ولذلك فالقيمة التي تحتاج إلى نوعَي علامات ASCII معًا تأخذ العلامات الطباعية (`“…”`، `’`). ويجوز أن تبدأ القيمة أيضًا بعلامة التنصيص المنحنية `“` أو بالقوس الزاوي `「` اللذين تكتبهما طريقة الإدخال الصينية، فتمتد حينئذ إلى `”` أو `」` المقابلة، بما في ذلك المسافات: `title=“甲戌本 眉批”`، `title=「脂批」`.
- **القيم المجرّدة** (`startAt=17`، `year=1998`) تمتد إلى المسافة التالية: `title=Hello world` هي `title="Hello"` ومعها راية `world`.
- **لا أقواس معقوصة.** لا يدخل `{` ولا `}` في قيمة أبدًا. أول `}` ينهي الكتلة: السور الذي تحمل قيمته واحدًا منهما لم يعد توجيهًا بل فقرة، وفي السطر يتسرّب باقي القيمة إلى النص. وفي العنوان، يترك القوس في القيمة الكتلة كلها في العنوان: `# Title {note="a {b"}` يُنضَّد كما كُتب. (حتى الإصدار postext 1.8 كان `{` بعد مسافة يبدأ الكتلة من جديد وكان `b` يُقرأ راية.)
- **علامات الدولار نص عادي.** تُقرأ السمات قبل الرياضيات السطرية، فـ`lead="from $5 to $6"` مجرد نص.
- **سطر واحد.** لا تمتد كتلة السمات على أكثر من سطر أبدًا.

```markdown
# The Long Road {lead='A "road novel", they said' price="$18"}

:::callout{type="note" title='The "fast" path'}
…
:::
```

أما `::resource{id="…"}` فأشدّ صرامة: المعرّف بين علامتَي تنصيص مزدوجتين ولا سمة أخرى (انظر [الموارد](#الموارد)).

### الحاويات

تلفّ الحاوية سلسلة من الكتل بسور: سطر افتتاح `:::name` أو `:::name{attrs}`، ثم أي محتوى عادي، من فقرات وعناوين وقوائم واقتباسات كتلية ومعادلات وحتى توجيهات أخرى، ثم سطر إغلاق يحمل `:::` مجرّدة. يجوز أن تتداخل الحاويات؛ وكل `:::` إغلاق يغلق أعمق حاوية مفتوحة.

```
:::callout{type="note"}
Keep the lantern lit **every** night.

- Check the wick.
- Trim it at dusk.
:::
```

يُتعرَّف على أربعة أسماء حاويات في تدفق النص (وخامس، `:::columns`، لا يعمل إلا داخل إطار، وهو مشروح أدناه). وما ترسمه كل حاوية يُضبط في قسمها الخاص من الإعدادات:

| الصياغة | الأثر |
| --- | --- |
| `:::callout{…}` … `:::` | محتوى داخل إطار: ملاحظة أو نصيحة أو تحذير منفصل عن المتن في إطار محدود أو ملوّن الخلفية. |
| `:::paragraphs{…}` … `:::` | سلسلة فقرات منضّدة بنمط فقرة مسمّى (مدخل تمهيدي، أو تصدير، أو مجموعة ملاحظات بخط صغير) بدلًا من نمط المتن. |
| `:::part{…}` … `:::` | افتتاح جزء أو قسم: يشكّل العنوان والنص المحاطان صفحة الافتتاح لتقسيم رئيسي. |
| `:::paper{…}` … `:::` | سلسلة صفحات مطبوعة على نوع ورق آخر، كقسم من اللوحات على ورق لامع في كتاب مطفأ اللمعة. لا يُظهرها إلا عارض Folio. |

السمات التي تقبلها كل حاوية، وطريقة تنسيقها، موثقة في [الإعدادات](/ar/docs/configuration). وقيم السمات تتبع قواعد التوجيهات نفسها. يأخذ سور `:::callout` السمة `type` (معرّف نمط إطار مُعدّ، والأنواع غير المعروفة أو الغائبة ترجع إلى النمط الأول)، و`title` (تتجاوز العنوان الافتراضي للنمط)، و`span` / `placement` (`column` أو `page` أو `side`؛ `here` أو `top` أو `bottom` أو `fixed`) لتجاوز امتداد النمط وموضعه لهذا الإطار:

```
:::callout{type="objectives" title="What you will learn" span="page" placement="top"}
- Name the parts of the lantern.
- Trim the wick without touching the glass.
:::
```

يُخرَج الإطار (callout) صندوقًا: عنوان اختياري، ثم محتواه منضّدًا بطباعة المتن والقوائم الخاصة بالنمط. يبقى متماسكًا افتراضيًا، فينتقل كاملًا إلى العمود أو الصفحة التالية إذا لم يتسع له المكان (والإطار الأطول من عمود كامل ينقسم مع ذلك بدلًا من أن يفيض)؛ والنمط الذي فيه `keepTogether: false` يتيح انقسامه بين كتله أو بين الأسطر، مع ترك `splitMinLines` من أسطر النص على الأقل، أو شكل أو جدول أو معادلة مستقلة أو إطار متداخل، في كل جانب من القطع (والقطع داخل فقرة أو عنصر قائمة يترك أيضًا `layout.boxChildSplitMinLines` من أسطرها على الأقل في كل جانب: سطران افتراضيًا، أو `splitMinLines` إذا كانت أقل؛ والكتب المحفوظة قبل الإصدار 1.5 التي تحوي فصولها إطارًا تُقرأ بالقيمة 1، أي قطع الإصدار 1.4). كل جزء بعد الأول يبدأ بلا أيقونة، وإن احتفظ نصه بعمود الأيقونة، وبلا عنوان ما لم يكرره النمط (`repeatTitle`: "Key points (cont.)")؛ ويمكن للنمط أيضًا أن يضع علامة «يتبع» تحت كل جزء يستمر بعده (`continuesMarkerEnabled`)؛ انظر [العلامات على الإطار المنقسم](/ar/docs/configuration#علامات-الإطار-المقسوم). الإطارات الممتدة بعرض الصفحة (`span="page"`) تقطع الصفحة إلى أشرطة أعمدة؛ والإطارات `span="side"` تخرج من التدفق إلى العمود الجانبي المخصص للعناصر العائمة في تخطيط العمود ونصف العمود (`layout.sideColumnRole: 'floats'`)، مكدّسةً بجوار النص الذي تقطعه، وتُخرَج إطاراتِ عمود حيث لا يوجد عمود كهذا؛ والإطارات `placement="fixed"` تخرج من التدفق وتُثبَّت على إحداثيات الصفحة (شارة تقييم ذاتي في الزاوية السفلية اليسرى من الصفحة الأخيرة لفصل ما مثلًا)، وتتخلى الأعمدة التي تغطيها عن تلك المنطقة؛ والإطارات العائمة (`placement="top"` / `"bottom"`) تخرج من التدفق حيث تقع وتأخذ أول شريط حرّ بعد ذلك الموضع، أي أسفل الصفحة أو أعلى التالية أو أسفلها، بينما يملأ النص الذي يليها الصفحة التي تركتها. والنمط الذي فيه `floatBarrier: true` (إطار «النقاط الرئيسية» الختامي للفصل عادة) يجعل الإطار **حاجزًا للعناصر العائمة** (float barrier): كل شكل أو جدول أُحيل إليه قبله يوضع قبله، في الخانات الحرّة من الصفحة أو في صفحات تُفتح قبل الإطار، فلا يفلت أي عنصر عائم إلى ما بعد نهاية فصله. والسور `:::name` غير المعروف ليس حاوية: يُعامل السطر نصًا، تمامًا كالتوجيه غير المعروف.

يأخذ سور `:::part` السمة `number` (كما تريد أن يُطبع: `"I"`، `"IV"`، `"3"`؛ ويُحلَّل أيضًا ليتمكن التصميم من إعادة تنسيقه) والسمة `title`؛ وكلتاهما اختيارية. وسمة ثالثة، `palette="band=#hex"` (عدة أزواج `id=#hex` مفصولة بفواصل)، تعيد تلوين كل لون في التصميم مرتبط بمعرّفات لوحة الألوان تلك، من الترويسات وشريط الافتتاح وتصاميم الأجزاء، وألوان تدفق النص التي تشاركها قيمتها الأساسية (العناوين والخط الغامق والإحالات وعلامات التنقيط والتعليقات والجداول والإطارات والشارات)، للجزء وللفصول التي تليه حتى الجزء التالي؛ انظر [الإعدادات › الأجزاء](/ar/docs/configuration#الأجزاء). تفتح الحاوية دائمًا صفحة خاصة بها: فاصل صفحات بالزوجية المُعدّة قبلها، وعمود متن واحد ضمن `parts.margins`، وتصميم الافتتاح على الصفحة كلها، وفاصل صفحات آخر بعد سور الإغلاق. أما المتن، وهو عادة قائمة الفصول التي يجمعها الجزء أو لا شيء على الإطلاق، فيُنضَّد بـ`parts.bodyStyle`:

```
:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
:::

# The lantern and its parts
```

مع إعدادات العناوين الافتراضية ينتج هذا التسلسل الكلاسيكي: صفحة الجزء في صفحة فردية، ثم صفحة زوجية فارغة، ثم الفصل في الصفحة الفردية التالية. وتُعلَن الصفحة بالدور `role: 'part'` لكي تتخطاها الترويسات والتذييلات، ويُستبدل `{partTitle}` / `{partNumber}` بالجزء الحالي في كل صفحة تالية. انظر [الأجزاء](/ar/docs/configuration#الأجزاء) في مرجع الإعدادات.

لا يحتاج السور إلى سطر فارغ قبله: سور الافتتاح أو الإغلاق الملتصق مباشرة تحت فقرة أو قائمة أو اقتباس كتلي ينهي تلك الكتلة. والحاوية التي تبقى مفتوحة في نهاية المستند تُغلق تلقائيًا هناك، ويُبلغ Sandbox عن تحذير **حاوية غير مغلقة** (Unclosed container) يشير إلى سطر الافتتاح. أما `:::` الشاردة بلا حاوية مفتوحة فتُترك في النص فقرةً ظاهرة بدلًا من أن تُحذف بصمت.

### `:::columns`

داخل `:::callout`، تنضّد مجموعة `:::columns{count=2}` … `:::` الكتل الواقعة بين سوريها في `count` من الأعمدة المتساوية العرض (يفصل بينها `columnGap` الخاص بالنمط): تُقطع السلسلة حيث تتوازن الأعمدة على أفضل وجه، بين الكتل أو بين أسطر فقرة أو عنصر قائمة يستمر ذيله في رأس العمود التالي بلا علامة تنقيطه، ويطول الإطار إلى طول أطول عمود. وتعود الكتل التي تلي المجموعة إلى العرض الكامل. وخارج الإطار تُتجاهل الأسوار وتتدفق الكتل كالمعتاد. وسمة `breaks` تثبّت بدايات الأعمدة بدلًا من الموازنة: `:::columns{count=2 breaks="4"}` يفتح العمود الثاني عند الكتلة الرابعة من المجموعة (وقائمة مفصولة بفواصل لأعمدة أكثر)، بلا قطع داخل فقرة، كعمود نص بجوار عمود شكل.

```md
:::callout{type="summary"}
:::columns{count=2}
- Every element is one kind of atom.
- Electrons live in orbitals.
- A bond shares or transfers electrons.
:::
:::
```

**كيف يعدّ `breaks`.** يرقّم `breaks` كتل المجموعة بالترتيب: الفقرات، وعناصر القوائم (كل عنصر كتلة)، والمعادلات المستقلة، والأشكال والجداول؛ ويُعدّ `:::callout` المتداخل كتلة واحدة مهما احتوى. التوجيهات ليست كتلًا: `:::space` بين مقطعين شعريين لا يغيّر العدّ. ويُتجاهل الرقم الأقل من 2، أو الواقع بعد آخر كتلة في المجموعة، أو غير الواقع بعد الفاصل السابق. وداخل المجموعة يفصل `:::space` بين كتلتين كما يفعل في أي موضع آخر من الإطار، ويختفي في أعلى المجموعة وفي رأس كل عمود من أعمدتها (موضع `breaks` أو قطع موازنة)؛ ولفتح المجموعة في موضع أدنى، ضع الفراغ قبل سور `:::columns`. ولذلك يصطف عمودان يحملان التباعد نفسه مقطعًا بمقطع:

```md
:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,

and trimmed before the dawn.

:::space

The keeper sleeps by day.

La lámpara se enciende al anochecer,

y se despabila antes del alba.

:::space

El farero duerme de día.
:::
:::
```

هنا تفتح الكتلة الرابعة، "La lámpara…"، العمود الثاني؛ ولا يُعدّ سطرا `:::space` ويتركان الفراغ نفسه في العمودين.

ويقبل سور `:::callout` أيضًا `label="…"`: النص الذي يطبعه النمط ذو لسان `label` على الزاوية العليا للإطار (`:::callout{type="box" label="BOX 1-1" title="The octet rule"}`).

و`:::callout` داخل آخر إطار قائم بذاته، كبطاقة ورقة عمل تحوي مربعات إجابة مثلًا. يأخذ نمطه الخاص (الخلفية والحد ونصف قطر الزوايا والحشو والعنوان والأيقونة) بكامل العرض الداخلي للإطار الخارجي ويتراص بين كتله الأخرى؛ وتُتجاهل `span` و`placement` الخاصتان به، لأن الإطار المتداخل يتدفق دائمًا داخل أصله. وكل سور يغلق أعمق إطار لا يزال مفتوحًا:

```md
:::callout{type="card"}
The statement of the exercise.

:::callout{type="answer"}
A white answer box with its own border and padding.
:::

:::callout{type="answer"}
A second answer box.
:::
:::
```

حين ينقسم الإطار الخارجي بين الأعمدة أو الصفحات (`keepTogether: false`، أو لأنه أطول من عمود)، ينتقل الإطار المتداخل كاملًا إلى الجزء التالي ما لم يسمح نمطه هو أيضًا بالانقسام؛ ويعيد كل جزء رسم الأطر التي يحويها، ويُسقط الإطار المتداخل المستمر أيقونته، وعنوانه ما لم يكرره نمطه (`repeatTitle`).

### `:::paper`

يمكن للكتاب أن يغيّر نوع الورق لسلسلة من الصفحات: قسم من اللوحات على ورق مطلي لامع في كتاب مطبوع على ورق غير مطلي، أو بطاقة مُدرجة، أو بضع أوراق من ورق ملوّن. لُفّ ذلك المحتوى بحاوية `:::paper`:

```md
:::paper{type=coatedGloss grammage=130}
## Plates
::resource{id="plate-1"}
::resource{id="plate-2"}
:::
```

يغطي نوع الورق أفرخًا كاملة، ولذلك يبدأ المحتوى الواقع بين السورين في صفحة جديدة، ويبدأ كل ما يلي `:::` الإغلاق في صفحة جديدة أيضًا. والسلسلة التي ينتهي بها المستند لا تترك بعدها صفحة فارغة. وتوضع الأشكال والجداول المُحال إليها داخل السلسلة قبل أن تُغلق. وكل صفحة منضّدة بمحتوى من داخل الحاوية تحمل نوع الورق في الإخراج (`VDTPage.paper`، والسمات كما يكتبها السور)؛ أما الصفحات خارجها فلا تحمل شيئًا. يقرؤه عارض Folio ويرسم تلك الأوراق بلون الورق وسطحه وسماكته وصلابته. وتتجاهله مخرجات اللوحة (Canvas) وPDF وHTML: تُنضَّد الصفحات وتُطبع كأي صفحات أخرى.

السمات هي سمات إعدادات `folio.paper`، وكلها اختيارية. والسمة التي يغفلها السور تتبع ورق المستند، وبعد ذلك القيم الافتراضية لنوع الورق:

| السمة | القيمة |
| --- | --- |
| `type` | نوع الورق: `uncoated`، `bookWove`، `coatedMatte`، `coatedSilk`، `coatedGloss`، `bible`، `newsprint`، `cardStock`، `board`. ويحدد القيم الافتراضية للسمات أدناه. |
| `grammage` | الوزن بوحدة g/m²، عدد أكبر من 0. الورق الأثقل أسمك وأصلب وأكثر عتامة. |
| `bulk` | السماكة لكل وحدة وزن بوحدة cm³/g، عدد أكبر من 0 (السماكة بالميكرومتر µm = grammage × bulk). |
| `finish` | السطح: `auto`، `uncoated`، `matte`، `silk`، `gloss`. |
| `texture` | بروز السطح: `auto`، `smooth`، `vellum`، `wove`، `laid`، `linen`، `felt`. |
| `textureStrength` | مدى ظهور الملمس، من 0 إلى 2. |
| `shade` | لون الورق: `#rgb` أو `#rrggbb` أو معرّف مدخل في `colorPalette`. |
| `showThrough` | `true` أو `false`: هل تظهر الصفحة الخلفية بخفوت من خلال الورق. و`showThrough` المجرّدة تعني `true`. |

و`:::paper` داخل أخرى لا تتجاوز إلا السمات التي تضبطها، وتبدأ هي أيضًا وتنتهي بفاصل صفحات. وداخل `:::callout` تُتجاهل الأسوار. والقيمة التي لا يستطيع المحرّك قراءتها تُسقط، ويسردها Sandbox تحذيرَ **سمة ورق غير صالحة** (Invalid paper attribute) (`paperAttributeInvalid` في `contentWarnings` الخاصة بالمستند).

### `:::pagebreak`

لا يفرض التوجيه نفسه الزوجية بمفرده، بل يؤثر في إخراج الكتلة التالية فقط. استخدمه لإنهاء مقدمة، أو لإجبار إهداء على صفحة خاصة به، أو لتعليم نهاية قسم. وحين يُراد فاصل صفحات وإعادة ضبط للترقيم في الموضع نفسه، ضع `:::pagebreak` ثم `:::numbering`: يُطبَّق تبديل الترقيم على الصفحة الجديدة التي أنشأها `:::pagebreak` للتو.

فاصل الصفحات في صفحة لا تزال فارغة لا يفعل شيئًا، فلا يضيف صفحة فارغة أبدًا. ولا يحلّ محل `breakBefore` لعنوان يليه مباشرة (للمستوى 1 واحد افتراضيًا): يظل العنوان يطبّق زوجيته، وقد يضيف ذلك صفحة فارغة بعد الصفحة التي فتحها التوجيه. ولبدء عنوان في ذلك الموضع بالضبط، أوقف فاصله (انظر **الإعدادات › أنماط العناوين**). وبعد عنوان غلاف يملأ صفحته يكون الفاصل اختياريًا: فالغلاف يحجز بالفعل بقية صفحته، في التخطيطات ذات العمود الواحد ومتعددة الأعمدة على السواء، و`:::pagebreak` بعده مباشرة لا يضر. ولا يلزم إلا بعد غلاف يتوقف تصميمه قبل أسفل الصفحة، حين ينبغي أن يبدأ النص مع ذلك في الصفحة التالية (انظر **الإعدادات › الارتفاع المحجوز**).

```md
The old chapter ends here.

:::pagebreak{parity="odd"}

# A new chapter
```

#### سمة الزوجية (parity)

تقبل السمة `parity` القيم الخمس نفسها التي يقبلها `headings.levels[*].breakBefore.parity`:

- `'any'`: القيمة الافتراضية، بلا قيد على الزوجية؛ يفتح الفاصل صفحة جديدة فحسب.
- `'odd'` / `'even'`: تُفتح الصفحة الجديدة في الجانب المطلوب من الصفحتين المتقابلتين؛ ولا تُدرج صفحة فارغة واحدة إلا إذا كانت الصفحة التالية الطبيعية في الجانب الخطأ.
- `'always-odd'` / `'always-even'`: تضمن صفحة فاصلة فارغة إلزامية واحدة على الأقل بين المحتوى السابق والصفحة الجديدة، ثم تفرض الزوجية. تتبع الصفحة الفارغة الفاصلة الفصل **السابق**؛ وأي حشو إضافي للزوجية يتبع ما يليه.

#### لمن تتبع الصفحة الفارغة

يميّز نموذج `VDTPage` بين نوعَي الصفحات الفارغة اللذين يمكن أن يُدخلهما `:::pagebreak` (و`breakBefore`):

- `blankForParity: true`: تُدرج لاستيفاء قيد الزوجية. وفي ترويسات `{chapterTitle}` تحمل هذه الصفحة عنوان الفصل **القادم**، لأن الصفحة الفارغة لا توجد إلا لدفع ذلك الفصل إلى الزوجية الصحيحة.
- `blankForForce: true`: الفاصل الإلزامي الذي يتقدّم في أوضاع `'always-*'`. وهو يتبع الفصل **السابق**: وقفة متعمدة في نهاية الفصل، لا حشوًا للزوجية لأجل الفصل التالي.

والقاعدتان نفسهما تعطيان الصفحة الفارغة ترويسات قسم منسَّق ولوحة ألوانه؛ انظر [الإعدادات › أنماط العناوين](/ar/docs/configuration#أنماط-العناوين).

#### استثناء بداية المستند

حين يكون `:::pagebreak` أول بنية في المستند على الإطلاق (أو حين يستدعي عنوان ذو `breakBefore` فاصلًا كهذا)، يُتخطى فرض الزوجية ما دامت الصفحة الأولى فارغة. فتقع الكتلة التالية في الصفحة 1 كما كُتبت، بصرف النظر عن الزوجية المطلوبة، بلا صفحة فارغة زائدة في البداية.

### `:::numbering`

بـ`:::numbering` تعيد تشغيل عدّاد الصفحات في منتصف المستند. ومثال الكتاب النموذجي:

```md
---
title: "A Book With Front Matter"
---

# Preface

…

:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}

# Chapter 1
```

تُرقَّم صفحات المقدمة `i`، `ii`، `iii`، …؛ ويبدأ الفصل الأول في صفحة فردية رقمها `1`.

تغييرات الصيغة وحدها (بلا `startAt`) تُبقي العدّاد مستمرًا، وهذا مفيد مثلًا للتحول من `lower-alpha` إلى `upper-alpha` بلا إعادة ضبط.

يقبل `format` أي تهجئة لصيغة ترقيم: `roman-lower` و`i` تعملان كما تعمل `lower-roman`، و`arabic` كما تعمل `decimal` (انظر [الإعدادات › تهجئات صيغ الترقيم](/ar/docs/configuration#صيغ-كتابة-أنماط-الترقيم)). والقيمة التي ليست أيًّا منها تترك الصيغة على حالها، وينبّه إليها Sandbox.

### `:::space`

يترك `:::space` فراغًا عموديًا بين كتلتين: لفصل سطر ختامي عن النص الذي فوقه، أو لإنزال تصدير أو توقيع قليلًا، أو لفتح *فاصل فراغ* بين مقطعين من النص. الأسطر الفارغة الزائدة في Markdown لا تفعل ذلك: فكما في أي Markdown، سلسلة الأسطر الفارغة مجرد فاصل فقرات واحد، وهذا يمنع المستند من تغيير إخراجه حين يضيف محرر أو منسّق مسافات بيضاء أو يحذفها.

```md
The last paragraph of the scene.

:::space

A new scene begins one line lower.

:::space{lines=2}

Two lines lower still.
```

- **`lines`**: مقدار الفراغ بأسطر المتن (شبكة خطوط الأساس). القيمة الافتراضية `1`. الأعداد الصحيحة تُبقي كل سطر نص على الشبكة، فتظل الأعمدة متحاذية عبر الصفحة؛ أما الكسر (`lines=0.5`) فيُحترم بدقة، على حساب ذلك التحاذي حتى الكتلة التالية التي تُلحَق بالشبكة. والقيمة التي ليست عددًا أكبر من 0 ولا تزيد على 20 ترجع إلى سطر واحد، وينبّه إليها Sandbox (**حجم مسافة غير صالح**، Invalid space size).
- **يُضاف ولا يُدمج.** يُضاف الفراغ إلى الهامش القائم بالفعل بين الكتلتين، كالهامش العلوي للعنوان أو الهامش السفلي للقائمة، بدلًا من أن يذوب فيه. وسطرا `:::space` متتاليان يضيفان سطرين.
- **يُسقط عند الفاصل**، مثل `\vspace` في LaTeX: يختفي في أعلى العمود أو الصفحة، فلا تبدأ صفحة بفجوة أبدًا؛ وإذا لم يتسع له المكان في أسفل العمود فإنه ينهي ذلك العمود فحسب، بلا ترحيل للباقي.
- **الفقرة التي تليه تُنضَّد بلا إزاحة.** حين يكون `bodyText.indentAfterHeading` معطّلًا، تفقد الفقرة الواقعة مباشرة بعد `:::space` إزاحة سطرها الأول، كما تفعل بعد العنوان، وهو العرف المعتاد للنص الذي يُستأنف بعد سطر فارغ.
- **داخل الإطار** (أو داخل مجموعة `:::columns`) يفصل بين أبناء الإطار بالطريقة نفسها، مقيسًا بأسطر متن الإطار الخاصة. وقبل الكتلة الأولى في الإطار يُسقط، كما في أعلى العمود، لأن الحشو يفصل المحتوى عن الإطار بالفعل، إلا في حالتين يفتح فيهما ذلك القدر من المكان: تحت عنوان الإطار مباشرة، وفي إطار لا يحوي شيئًا آخر (مربع إجابة، أو فراغ للكتابة فيه، يُقاس بالأسطر). ويختفي دائمًا في أعلى مجموعة `:::columns`، وفي رأس كل عمود من أعمدتها، وفي أعلى الجزء من الإطار المنقسم الذي يستمر في العمود أو الصفحة التالية. وداخل حاوية `:::paragraphs` يعمل كما يعمل بين فقرات المتن.
- **الإبقاء مع التالي** يحسب حسابه: العنوان الذي يليه `:::space` ينتقل إلى الأمام حين لا يتسع تحته الفراغ والأسطر الأولى من نصه.

مربع الإجابة في ورقة العمل إطار لا محتوى له سوى الفراغ: السؤال في عنوانه، وتحته متسع لأربعة أسطر.

```md
:::callout{type="answer" title="1. Name the three parts of the lantern."}
:::space{lines=4}
:::
```

للحصول على فاصل ثابت بدلًا من فراغ، استخدم `:::columnbreak` أو `:::pagebreak`.

### `:::verse`

قصيدة بالتخطيط العربي الكلاسيكي (قصيدة أو قطعة): كل بيت في سطر واحد بشطرين، الصدر في جانب البداية (اليمين في العربية) والعجز في جانب النهاية، وبينهما فجوة. اكتب بيتًا في كل سطر، وافصل شطريه بـ`||` (وتعمل أيضًا `\\` مع مسافة على كل جانب، كما في نصوص Wikisource). والسطر الذي لا فاصل فيه شطر منفرد، يوضع في وسط القصيدة.

```md
فأنشد يقول:

:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::
```

- **عرض واحد.** يُنضَّد كل شطر في القصيدة بعرض واحد، فيبدأ كل صدر على خط عمودي واحد وينتهي كل عجز على خط آخر، وتصطف حروف الروي على طول القصيدة. والعرض هو عرض أعرض شطر، على ألا يزيد على نصف عرض السطر مطروحًا منه الفجوة؛ ويضبطه `width` (`width=55mm`). ويُبلغ كل شطر هذا العرض بالكشيدة أولًا (يمدّ الشعر أكثر من النثر: ضعف `bodyText.kashidaMaxLength`)، ثم بالمسافات بين كلماته؛ والشطر المكوّن من كلمة واحدة لا تستطيع ملأه يترك الباقي في الفجوة.
- **الفجوة** 2 em افتراضيًا؛ ويضبطها `gap` (`gap=3em`، والعدد المجرّد بوحدة em). ويطبع `ornament` علامة في وسطها (`ornament="٭"`)، وهي ليست جزءًا من النص.
- **أعرض من اللازم.** الشطر الأعرض من العرض المشترك يضيّق أولًا المسافات بين كلماته إلى `bodyText.minWordSpacing`. فإن لم يتسع بعد ذلك، نُضِّد بيته مدرّجًا: الصدر محاذيًا لجانب البداية في سطر خاص به، والعجز محاذيًا لجانب النهاية في السطر التالي.
- **الموضع.** توضع القصيدة في وسط العمود؛ و`align=start` يحاذيها لجانب البداية. لا يُقسم البيت أبدًا بين عمودين أو صفحتين، وتتبع القصيدة قواعد الأسطر اليتيمة (orphans) والأرامل (widows) التي تتبعها الفقرات (القصيدة ذات ثلاثة أبيات أو أقل تبقى كاملة). والفقرة التي تسبق القصيدة وتقدّم لها («فأنشد يقول:») تُبقي سطرها الأخير مع الأبيات الأولى.
- **الحرف.** تأخذ القصيدة محرف نص المتن وحجمه وتباعد أسطره؛ ويسمّي `style` نمط فقرة لها (`style="verse"`)، وبهذا تحصل القصيدة المشكولة على التباعد الإضافي الذي تحتاجه حركاتها. ويضبط `dir=ltr` أو `dir=rtl` اتجاهها كأي كتلة؛ والقصيدة المكتوبة بالحروف اللاتينية في كتاب من اليسار إلى اليمين يكون صدرها على اليسار.

يُبقي النص الخام للقصيدة الأشطر والأبيات منفصلة (بعلامة جدولة وفاصل سطر)، فيقرؤها البحث أو المقطع المنسوخ كما كُتبت؛ وتُستبعد الكشائد والزخرفة.

### `:::toc`

يطبع `:::toc` جدول المحتويات حيث يقع. ويتمدد إلى كتل عادية، واحدة لكل عنوان من المستويات التي يسردها `toc.levels` (المستوى 1 افتراضيًا) وواحدة لكل `:::part`، فتتدفق المحتويات عبر الأعمدة والصفحات كأي نص آخر، والنقر على مدخل ينقلك إلى سطر التوجيه. يُظهر المدخل رقم العنوان (مخرجات `numberingTemplate` الخاصة به، وإلا فترتيب الفصل)، وعنوانه، وخطًا منقّطًا، ورقم الصفحة التي يبدأ فيها، وحين يكون `toc.subtitle` مفعّلًا، سطرًا ثانيًا فيه سمة من سمات العنوان مثل `{author="…"}` للفصل. ويحصل الجزء على صف خاص به، يصممه `toc.parts.design` ويلوّنه `palette` الخاص بالجزء. والعناوين التي في نمطها `numbered: false` تُدرج بلا رقم؛ و`{toc="false"}` على عنوان يُبقيه خارجها (عنوان المحتويات نفسها عادة).

```md
# Contents {style="front-matter" toc="false"}

:::toc
```

أرقام الصفحات هي الأرقام التي يطبعها المستند فعلًا. فالمستند المُخرَج وحده يُعاد إخراجه بأرقام الجولة السابقة حتى تكفّ عن التغيّر؛ ومع إعادة بدء الترقيم بعد الصفحات التمهيدية (وصفة `:::numbering` أعلاه) تكفي جولة إضافية واحدة لتستقر. أما الفصل المُخرَج وحده (معاينات Sandbox) فيتلقى مخطط الكتاب كله من مضيفه بدلًا من ذلك. انظر [جدول المحتويات](/ar/docs/configuration#جدول-المحتويات) في مرجع الإعدادات.

### `:::index`

يطبع `:::index` الفهرس الأبجدي في آخر الكتاب حيث يقع: المصطلحات المعلَّمة بـ`:index[…]` أو `:index{term="…"}` في أنحاء الكتاب، مع صفحاتها التي تتبع النص كلما تحرك. وهو مشروح مع العلامات في [الفهرس الأبجدي](#الفهرس-الأبجدي).

```md
# Index {style="index"}

:::index
```

### فواصل الأسطر في العناوين

اكتب `\\` داخل عنوان (أو داخل السمة `title` لجزء) لفرض فاصل سطر حيث يُعرض العنوان بوصفه عنوانًا: يستمر العنوان داخل العمود في التدفق ويُظهر مسافة في ذلك الموضع، بينما يكسر `{titleText}` في تصميم الافتتاح السطر عند تلك النقطة (في كل أوضاع `overflow` لعنصر النص). أما الترويسات و`{chapterTitle}` و`{partTitle}` ومخطط PDF فترسم العنوان دائمًا في سطر واحد. وفي الصينية أو اليابانية يُقرأ الفاصل مسافةً إيديوغرافية بين حرفين من ذلك النظام (عنوان من شطرين متقابلين)؛ وحيث يلتقي أحدهما برقم أو نص لاتيني (`关于举办 \\ 2026年…`) تضع الصفحة مسافة الفصل بين الحروف الهانية واللاتينية، وتضمّ إشارات PDF المرجعية وعنوان المستند النصفين بلا شيء بينهما، كما يُكتب النص الصيني العادي.

```md
# Concepts of health and illness. \\ Community health {author="I. Zango Martín"}
```

## التنسيق المضمّن

يُتعرَّف على الترميز المضمّن داخل أي كتلة نصية (العناوين والفقرات والاقتباسات الكتلية وعناصر القوائم). وفي العنوان يتبع الإعداد `headings.inlineMarks`، المفعّل افتراضيًا: يُطبع ما في العنوان من مائل وعريض وأحرف فوقية وسفلية وحروف كبيرة مصغّرة وروابط كما يُطبع في الفقرة، ويخرج المقطع المائل في عنوان مائل قائمًا. وإذا أُوقف الإعداد أُسقطت العلامات وطُبع العنوان بنمطه الخاص؛ وعلى هذا النحو تُقرأ الإعدادات التي حفظها postext 1.4 أو ما قبله إذا كانت عناوينها تحمل علامات (انظر [الإعدادات › العناوين](/ar/docs/configuration#العناوين)). أما تصميم العنوان فيطبع `{titleText}` نصًا عاديًا في الحالتين.

> **شكل: التنسيق المضمّن في لمحة**
> مقارنة بين Markdown والنتيجة المعروضة للعريض والمائل والعريض المائل والشيفرة المضمّنة والروابط.
>
> *Markdown على اليسار، والنتيجة المعروضة على اليمين.*

| الترميز | الصيغة | ملاحظات |
| --- | --- | --- |
| عريض | `**bold**` أو `__bold__` | يُرسم بالوزن `bodyText.boldFontWeight`. ويستبدل الإعداد الاختياري `bodyText.boldColor` لونَ المتن الافتراضي في المقاطع العريضة. |
| مائل | `*italic*` أو `_italic_` | يُرسم بالشكل المائل من عائلة الخط الحالية. ويستبدل الإعداد الاختياري `bodyText.italicColor` لونَ المتن الافتراضي في المقاطع المائلة. لا تدلّ الشرطة السفلية على التوكيد إلا عند حدّ كلمة، كما في CommonMark: الشرطة الواقعة بين حرفين أو رقمين — `snake_case_name`، أو `SR_AIR_EN.pdf` في عنوان URL — تبقى نصًا (وكذلك في `__bold__`)؛ وداخل الكلمة استعمل النجمات (`un*believ*able`). ولا تُحتسب هنا حروف الصينية واليابانية والكورية، لأن هذه الكتابات لا مسافات فيها: `中文_斜体_中文` و`中文__粗体__中文` مائل وعريض. والشرطتان `__` اللتان لا تصنعان عريضًا لا تصيران مائلًا أبدًا: تبقى `foo__bar__baz` نصًا. |
| عريض مائل | `***both***` أو `___both___` | تجتمع الخاصيتان. |
| حرف فوقي | `^text^` | يُنضَّد بنسبة 58% من حجم النص ويُرفع ثلث ذلك الحجم — أُسّ (`10^-8^`)، أو شحنة أيون (`Na^+^`). يبدأ النص المعلَّم وينتهي بحرف غير المسافة؛ وتبقى علامة الإقحام المنفردة في النثر حرفًا حرفيًا، وكذلك الوجهان `^_^` و`^o^` (أما `n.^o^` و`1^o^` فتبقيان حرفين فوقيين). |
| حرف سفلي | `~text~` | بالحجم نفسه، ويُخفض 0.15 من حجم النص فيبقى ضمن نطاق الأذيال السفلية — دليل كيميائي (`H~2~O`، `p<em>K</em>~a~`). والمدّة (~) التي على جانبيها رقمان مدى، فتبقى حرفًا حرفيًا: `3~5 days`، `需要3~5天`. وكذلك المدّة الواقعة بين كلمتين صينيتين، فلا تفتح حرفًا سفليًا: `周一~周五`، `北京~上海`؛ ومع ذلك يُغلق الحرف السفلي قبل حرف صيني (`F~合~等于`). يجتمع مع العريض والمائل (`**H~2~O**`). والحرف السفلي والحرف الفوقي المكتوبان معًا دون شيء بينهما يُكدَّسان كما في الصيغة: `*T*~0~^2^` تضع 2 فوق 0 أيهما جاء أولًا، ويُخفض الحرف السفلي 0.25 من حجم النص ليبتعد عن الفوقي، ويأخذ الزوج عرض الأعرض منهما. وإذا فصلت بينهما مسافة أو حرف نُضِّدا متتاليين؛ وكذلك يفعل رابط الكلمات (U+2060)، دون أن يظهر بينهما شيء. ولا ينفصل الزوج المكدَّس عند فاصل السطر أبدًا: الكلمة الأعرض من السطر تنكسر قبل الزوج. |
| حروف كبيرة مصغّرة | `:smallcaps[text]` | تُنضَّد الحروف الصغيرة حروفًا كبيرة بنسبة 70% من حجم النص — اسم شخصية في مسرحية، أو اختصار في النص الجاري. تقبل علامات أخرى داخلها وحولها؛ انظر [الحروف الكبيرة المصغّرة](https://postext.dev/ar/docs/document-format#الحروف-الكبيرة-المصغّرة). |
| الاتجاه في النص العمودي | `:tcy[12]`، `:upright[GDP]`، `:sideways[12]` | في النص العمودي: خانة واحدة قائمة (tate-chu-yoko)، أو كل حرف قائم في خانة خاصة به، أو المقطع كله مُدار. لا أثر لها في النص الأفقي؛ انظر [الاتجاه في النص العمودي](https://postext.dev/ar/docs/document-format#الاتجاه-في-النص-العمودي). |
| العلامات الصينية | `:dots[不可]`، `:name[賈寶玉]`، `:book[石頭記]` | نقاط التوكيد (着重号)، وخط أسماء الأعلام (专名号)، وعلامة عنوان الكتاب (书名号: 《》 أو خط متموّج، بحسب `cjk.bookTitleMark`). يبقى النص كما كُتب؛ انظر [العلامات الصينية والقراءات (ruby) والتعليقات السطرية (warichu)](https://postext.dev/ar/docs/document-format#العلامات-الصينية-والقراءات-ruby-والتعليقات-السطرية-warichu). |
| القراءات (ruby) | `:ruby[紅樓]{rt="hóng lóu"}` أو `{紅樓\|hóng\|lóu}` | قراءات بالبينيين (pinyin) أو الجوين (zhuyin) فوق الحروف الأساسية (أو بجانبها). تحتاج الصيغة المختصرة إلى أساس من حروف الهان أو الكانا أو البوبوموفو، لذا تبقى `{x\|x>0}` نصًا. |
| التعليق السطري (warichu) | `:warichu[note]{open="〔" close="〕"}` | تعليق يُنضَّد في صفّين بنصف الحجم داخل السطر (双行夹注)، ويُقسَم عبر الأسطر والصفحات. |
| الشيفرة المضمّنة | ```code``` | تُحذف علامات الاقتباس المائلة؛ ويُرسم المقطع نصًا عاديًا كما كُتب بالضبط: ما بداخله من `:ref{…}` أو شارة أو صيغة رياضية أو رابط أو علامة توكيد يُطبع حرفيًا، وبهذا يعرض النص الصيغة. أما تنسيق الشيفرة المميّز فمدرج في خطة العمل. |
| التهريب | `\*`، `\_`، `\^`، `\~`، ``\```، `\$` | تُنضّد الشرطة المائلة العكسية حرف العلامة نفسه — نجمة حاشية الجدول (`\* pOH = −log [OH^−^]`)، أو علامة إقحام حرفية، أو علامة دولار لا تفتح صيغة — بدل أن تفتح مقطعًا. تعمل في المتن وفي الشارات وفي التعليقات والخلايا والحواشي. (حتى postext 1.4 كانت التعليقات والخلايا والحواشي والشارات تطبع الشرطة المائلة العكسية في `\$`.) |
| مسافة غير فاصلة | الحرف نفسه: U+00A0 وU+202F وU+2007 | تلصق الكلمتين على جانبيها، فلا ينكسر السطر بينهما أبدًا: عدد ووحدته (37 °C)، أو إحالة إلى صفحة (ص. 12)، أو مجموعة آلاف (225 000). المسافة غير الفاصلة (U+00A0)، والمسافة الضيقة غير الفاصلة (U+202F)، ومسافة الرقم (U+2007) كلها تلصق — في المتن والتعليقات والخلايا والإطارات والترويسات — وتحتفظ كل منها بعرضها: ضبط الأسطر يمدّ المسافات بين الكلمات وحدها. كثير من الخطوط لا تملك رسمًا للمسافة الضيقة غير الفاصلة أو لمسافة الرقم؛ فتُنضَّدان حينئذ كما تنضّدهما المتصفحات، في Canvas وفي HTML وفي PDF على السواء: نصف مسافة كلمة، وعرض رقم. وتكاد كل الخطوط تملك U+00A0، فهي الخيار الآمن. والمجموعة الملتصقة على هذا النحو إذا كانت أعرض من السطر كله تنكسر عند آخر مسافة غير فاصلة فيها لا داخل كلمة. ويلصق رابط الكلمات (U+2060) دون أن يشغل حيزًا. اكتب الحرف نفسه: كيان HTML مثل ` ` يُطبع كما كُتب. انظر [حيث لا ينكسر السطر أبدًا](/ar/docs/justification#حيث-لا-ينكسر-السطر-أبدًا). |
| رابط | `[text](https://…)` | يبقى النص الظاهر في التدفق، منضّدًا كما يُنضَّد بلا رابط تمامًا. ويجعل عنوان URL الكلماتِ رابطًا فعّالًا في مخرجات HTML وPDF؛ انظر [الروابط](https://postext.dev/ar/docs/document-format#الروابط). |
| صورة | `![alt](src)` | **تُحذف** صيغة Markdown للصورة المضمّنة من النص. يجب التصريح بالصور في `PostextContent.resources` ليضعها محرّك الإخراج وفق قواعد `resourcePlacement`. |
| شارة | `:chip[text]` | مقطع نصي داخل إطار يلتف كوحدة واحدة — بنك كلمات، أو مفتاح، أو وسم. يُنسَّق بـ`chipStyles`؛ انظر [الشارات المضمّنة](https://postext.dev/ar/docs/document-format#الشارات-المضمّنة). |
| صيغة رياضية مضمّنة | `$…$` | صيغة LaTeX تجري مع النص المحيط بها، مثل `$e^{i\pi}+1=0$`. ينضّدها MathJax وتُرسم مسارات متجهية في كل المُخرِجات. استعمل `\\$` لعلامة دولار حرفية. أما التحجيم وصيغة العرض (`$$ … $$`) ومعالجة الأخطاء فمشروحة في [الصيغ الرياضية](https://postext.dev/ar/docs/document-format#الصيغ-الرياضية). |

### الروابط

رابط Markdown، `[text](url)`، يُبقي نصه في التدفق كما كان سيُنضَّد بدونه تمامًا: لا يغيّر الرابط فواصل الأسطر ولا المسافات ولا اللون أبدًا. ويحتفظ بعنوان URL للمخرجات التي تستطيع اتباعه:

- **HTML** (`renderToHtml`): تُلفّ الكلمات المرتبطة في `<a href="…" rel="noopener noreferrer">`، الذي يأخذ لون النص بلا خط تحته. وثمة مرساة واحدة لكل سلسلة من الكلمات المرتبطة في السطر.
- **PDF** (`postext-pdf`): تصير كل سلسلة من الكلمات المرتبطة في السطر تعليقًا توضيحيًا لرابط URI قابلًا للنقر. وفي PDF الموسوم يكون عنصر `Link` نصُّه الكلمات المرتبطة.
- **Canvas**: يُرسم نصًا عاديًا، إذ لا سطح للنقر في Canvas.

```markdown
Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration")
or write to [the team](mailto:team@example.com).
```

- قد تحمل الوجهة عنوانًا، ويُتجاهل (`[text](https://example.com "Title")`). وقد تُلفّ أيضًا بين قوسين زاويين، وحينئذ تصير المسافات `%20` (`[text](<https://example.com/a b>)`).
- لا يُحتفظ إلا بالوجهات الآمنة: `http:` و`https:` و`mailto:` و`tel:` و`ftp:` وعناوين URL النسبية (`../guide`، `#top`). وأي مخطط آخر (`javascript:`، `data:`، `file:`…) يُنضّد النص بلا رابط. ولا يربط PDF إلا عناوين URL المطلقة.
- قد تحتوي الوجهة على أقواس ما دامت متوازنة، كما في CommonMark: `[photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg)` يربط عنوان URL كاملًا. وتهرّب الشرطة المائلة العكسية حرفًا (`\(`، `\_`). فإن لم تتوازن الأقواس انتهت الوجهة عند أول `)` ونُضِّد النص بلا رابط؛ رمّز القوس المنفرد بـ`%28` أو `%29`. وتُنهي المسافة الوجهة أيضًا ما لم تكن ملفوفة بين قوسين زاويين.
- الكلمة الملتصقة بنص الرابط تشاركه الرابط. ففي `see [the site](https://example.com).` تدخل النقطة في المساحة القابلة للنقر.
- قد يحمل نص الرابط توكيدًا (`[**bold** words](…)`) وقد يقع داخله (`**[words](…)**`).
- تعمل الروابط في الفقرات وعناصر القوائم والاقتباسات الكتلية والإطارات والتعليقات والحواشي وخلايا الجداول، وفي العناوين ما دام `headings.inlineMarks` مفعّلًا (وهو الافتراضي). أما الترويسات والمخطط التفصيلي وصفوف المحتويات المأخوذة من عنوان فتحتفظ بالنص وحده، وكذلك نص `:chip[…]`.
- لا يُتعرَّف على الروابط المرجعية (`[text][id]`) ولا الروابط التلقائية (`<https://…>`) (انظر [ما لا يُدعَم](#ما-لا-يدعمه-postext)).

في VDT تكون الوجهة على كل مقطع مرتبط، في `VDTLineSegment.href`. ويحتفظ المحلّل بروابط المقطع نطاقاتٍ من نصه، في `InlineSpan.links`، ولا يقسم مقطعًا من أجل رابط أبدًا، ولهذا لا يستطيع الرابط أن يغيّر الإخراج.

### الشارات المضمّنة

يُنضّد `:chip[text]` النصَّ `text` داخل إطار — «شارة» (chip) مستديرة الحواف ملوّنة بلون خفيف — يجري مع السطر: كلمات بنك الكلمات أو تمرين التصنيف، ومفاتيح لوحة المفاتيح، والوسوم. ويختار `:chip[text]{style="key"}` نمطًا مسمّى من `chipStyles` (انظر مرجع الإعدادات)؛ ومن دون `style`، أو بمعرّف لا يصرّح به أي نمط، تأخذ الشارة النمط الأول (نمط `chip` مدمجًا إن لم يكن في الإعدادات أي نمط؛ وتحذّر Sandbox من المعرّف غير المعروف).

```markdown
Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb]

Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy.
```

- **وحدة واحدة.** لا تُكسر الشارة ولا تُقسَم بالواصلة من داخلها أبدًا؛ ينكسر السطر بين الشارات، عند مسافات الكلمات المحيطة بها. والشارة الأعرض من السطر كله تفيض عنه بدل أن تنقسم.
- **العرض.** تقدّمها هو النص مضافًا إليه الحشو الأفقي والحدّ الخارجي على الجانبين. ويمدّ ضبط الأسطر المسافات بين الكلمات وحدها، لا داخل الشارة أبدًا. و`gap` في النمط هو أقل حيّز يُترك بين الإطار وكلمة أو شارة مجاورة عبر مسافة — وتُزاد المسافة الأضيق منه (لا عند طرف السطر، ولا إلى جوار علامة ترقيم ملتصقة مثل `:chip[a],`).
- **الارتفاع.** الإطار شريط حول خط الأساس، 0.8 em فوقه و0.25 em تحته بحجم الشارة، يزيده الحشو العمودي والحدّ الخارجي. ويُرسم الحشو العمودي خارج صندوق السطر ولا يغيّر ارتفاع السطر أبدًا، فتبقى شبكة خطوط الأساس ثابتة؛ والإطار الأطول من خطوة السطر قد يصطدم بشارة في السطر الأعلى أو الأسفل، وتنبّه Sandbox إلى شارتين في سطرين مختلفين تتداخلان («الشارات تلامس السطر التالي») ليُقلَّل الحشو أو الحدّ الخارجي أو الحجم.
- **النص.** يأخذ نص الشارة علاماته المضمّنة الخاصة (`:chip[**bold** word]`، `:chip[x^2^]`) والتوكيد المحيط به (`**:chip[a]**`)؛ وقد يحدّد النمط عائلة الخط والحجم واللون والعريض والمائل. اكتب `\]` لقوس معقوف حرفي داخلها. وتبقى الإحالات وعيّنات الألوان والصيغ الرياضية داخل الشارة حرفية، ويطبع `\$` علامة دولار (حتى postext 1.4 كان يطبع الشرطة المائلة العكسية أيضًا).
- **الفارغة.** الشارة المؤلفة من مسافات وحدها (`:chip[ ]`، بما فيها المسافات غير الفاصلة) إطار فارغ — خانة إجابة، أو علامة نهاية: عرضها بقدر الحشو الأفقي لنمطها وحدّه الخارجي، وارتفاعها كارتفاع شارة فيها كلمات. حدّد حجم الخانة بـ`paddingX` في النمط (`:chip[ ]{style="blank"}`). وإذا لم يكن بين القوسين شيء على الإطلاق بقيت `:chip[]` نصًا حرفيًا.
- **المواضع.** الفقرات وعناصر القوائم والاقتباسات الكتلية والإطارات وخلايا الجداول والتعليقات والحواشي. أما العناوين فتُبقي `:chip[…]` نصًا حرفيًا.
- **المخرجات.** ترسم Canvas وHTML وPDF الإطار وتنضّد الكلمات نصًا حقيقيًا: قابلًا للتحديد في HTML، وقابلًا للاستخراج وبترتيب القراءة في PDF (في PDF الموسوم يكون الإطار عنصرًا زخرفيًا من عناصر الإخراج، وتنتمي الكلمات إلى الفقرة).

### الحروف الكبيرة المصغّرة

يُنضّد `:smallcaps[text]` النصَّ `text` بالحروف الكبيرة المصغّرة (small capitals) — أسماء الشخصيات في مسرحية، أو اختصار في النص الجاري، أو الكلمات الأولى من فصل. تُنضَّد الحروف الصغيرة حروفًا كبيرة بنسبة 70% من حجم النص، بينما تحتفظ الحروف الكبيرة والأرقام وعلامات الترقيم بالحجم الكامل، فيطبع `:smallcaps[Hamlet]` حرف H بالحجم الكامل يليه AMLET بحروف كبيرة مصغّرة.

```markdown
Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading.

The :smallcaps[unesco] report and the :smallcaps[who] guidelines.
```

- **مُركَّبة.** تُرسم الحروف الكبيرة المصغّرة من الحروف الكبيرة في الخط نفسه، بالطريقة نفسها في Canvas وفي HTML وفي PDF، فيُقاس النص وينكسر على نحو متطابق في كل مكان. ولا تُستعمل الحروف الكبيرة المصغّرة الحقيقية في الخط (خاصية OpenType `smcp`)؛ فإن أردتها فنضّد النص بعائلة خط مخصصة لها (عائلة ينتهي اسمها بـ«SC»، مثلًا) من خلال نمط فقرة.
- **العلامات.** يأخذ النص علاماته المضمّنة الخاصة (`:smallcaps[**Ophelia**]`) والتوكيد المحيط به (`*:smallcaps[Act I]*`)؛ اكتب `\]` لقوس معقوف حرفي داخله. والإحالة أو الشارة داخله تُنضَّد بالحروف الكبيرة المصغّرة أيضًا، وتبقى الإحالة رابطًا واحدًا في HTML وفي PDF؛ أما الصيغة الرياضية فلا.
- **الانكسار.** تلتف الكلمات وتُقسَم بالواصلة كالمعتاد؛ ويقرأ تقسيم الكلمات بالواصلة كل كلمة بحالة حروفها الأصلية.
- **المواضع.** الفقرات وعناصر القوائم والاقتباسات الكتلية والإطارات وخلايا الجداول والتعليقات والحواشي، والعناوين ما دام `headings.inlineMarks` مفعّلًا (وهو الافتراضي)؛ فإذا أُوقف حُذف الترميز من العنوان وطُبع النص كما كُتب.
- **الفقرات الكاملة.** نمط الفقرة أو متن الإطار الذي فيه `smallCaps: true` يُنضّد نصه كله على هذا النحو (انظر [أنماط الفقرات](/ar/docs/configuration#أنماط-الفقرات)).
- **النص.** يحمل Canvas وHTML وPDF الحروف كما رُسمت: نسخ `:smallcaps[Hamlet]` يعطي «HAMLET».

### الاتجاه في النص العمودي

في النص العمودي (`layout.writingMode: 'vertical-rl'`) تقف الحروف الصينية قائمة، وتُدار الكلمات اللاتينية والأعداد الطويلة على جانبها، ويقف العدد المؤلف من رقمين على الأكثر قائمًا في خانة واحدة، ما لم يقع في جملة لاتينية فيتبع كلماتها (انظر [الإعدادات › الأعداد في النص العمودي](/ar/docs/configuration#الأرقام-في-النص-العمودي)). وثلاث علامات تميّز مقطعًا باليد:

```markdown
第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。
```

- `:tcy[…]` (tate-chu-yoko، 縱中橫) تُنضّد نصها متجاورًا في خانة قائمة واحدة عرضها em واحد، وتضغطه عرضًا إذا كان أعرض منها: `:tcy[120]`، `:tcy[3.0]`، `:tcy[A+]`. ويُقرأ جيدًا ما يصل إلى أربعة حروف تقريبًا.
- `:upright[…]` تُقيم كل حرف في خانة خاصة به، والحروف اللاتينية في وسطها: اختصار يُقرأ حرفًا حرفًا نزولًا في العمود. ولا ينكسر السطر داخلها أبدًا.
- `:sideways[…]` تُدير المقطع كله مع السطر، والحروف الصينية أيضًا: عدد من رقمين يريده المؤلف على جانبه.
- يبقى النص في النص العادي؛ وتأخذ العلامات داخلها علامات مضمّنة أخرى (`:tcy[**12**]`) ورابطًا (`:sideways[[iPhone](https://…)]`) وبعضها بعضًا، والغلبة للأعمق (`:tcy[:upright[AB]]` تُقيم A وB)، واكتب `\]` لقوس معقوف حرفي. ولا تغيّر شيئًا في النص الأفقي.
- الإحالة أو علامة الحاشية أو الصيغة الرياضية أو الشارة أو عيّنة اللون داخل علامة تحتفظ بتنضيدها الخاص: `:sideways[iPhone[^1]]` تُدير iPhone وتترك رقم الحاشية كما يُنضَّد كل رقم حاشية؛ ويقف رقم الإحالة في خانة واحدة وفق `cjk.uprightDigits` كأي عدد قصير.
- عنصر النص في التصميم الذي فيه `inlineMarks: true` يأخذها أيضًا حين يُنضَّد عموديًا (انظر [الإعدادات › عناصر النص العمودية](/ar/docs/configuration#عناصر-النص-العمودي)).
- في الانكسار وضبط الأسطر تُحتسب خانة `:tcy` وكل حرف من `:upright` حروفًا صينية، ولا تُوضع بجوارها مسافة بين الهان واللاتينية.

### العلامات الصينية والقراءات (ruby) والتعليقات السطرية (warichu)

تعلّم الطبعات الصينية النص بين الأسطر بدل المائل أو التسطير، وتشرح الحروف بقراءاتها، وتُنضّد الشروح داخل السطر. وخمسة توجيهات تفعل ذلك. ويشرح [الإخراج الصيني](/ar/docs/chinese-layout) الأعراف التي تقوم عليها. وتحتفظ هذه التوجيهات بنصها: تبقى الحروف بين القوسين في الفقرة (يقرؤها البحث والمحتويات ومراسي الفهرس والنص المنسوخ كما كُتبت)، وتأخذ التوجيهات العلامات المضمّنة الأخرى داخلها وحولها، المتداخلة منها أيضًا. اكتب `\]` لقوس معقوف حرفي.

```markdown
此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。

{滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。

寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：……
```

- **`:dots[text]`** تضع نقطة توكيد (着重号) تحت كل حرف في النص الأفقي، وعلى يمينه في النص العمودي، ولا شيء على علامات الترقيم أو المسافات. `style="dot|circle|sesame"` (الافتراضي `dot`)، و`fill="open"` للمفرّغة، و`pos="over|under"` للجهة الأخرى. والتوكيد بصيغة Markdown `*…*` على حروف صينية يفعل الشيء نفسه مع `cjk.emphasis: 'dots'`، وهو الافتراضي في المستند الصيني؛ وتبقى الحروف اللاتينية في التوكيد نفسه مائلة.
- **`:name[text]`** ترسم خط أسماء الأعلام (专名号) تحت النص (وعلى يساره في النص العمودي)، و**`:book[text]`** ترسم علامة عنوان الكتاب (书名号): 《》 حول العنوان (و〈〉 للعنوان داخل عنوان آخر)، أو الخط المتموّج في الطبعات الكلاسيكية والتايوانية، أو لا شيء، بحسب `cjk.bookTitleMark` (افتراضيًا الأقواس في البر الرئيسي، والخط المتموّج في تايوان وهونغ كونغ). فمصدر واحد يخدم طبعة حديثة للبر الرئيسي وأخرى كلاسيكية. والاسمان أو العنوانان المتجاوران يبقى خطاهما منفصلين.
- **`:ruby[base]{rt="…"}`** تُنضّد القراءات فوق الأساس (بينيين)، أو على يمين كل حرف (جوين، الافتراضي لقراءات البوبوموفو). فإذا كانت القراءات بعدد الحروف، مفصولة بمسافات أو `|`، أخذ كل حرف قراءته وجاز أن ينكسر السطر بينها (mono ruby)؛ أما `group`، أو عدد لا يطابق، فيُنضّد قراءة واحدة في الوسط فوق الأساس كله، ولا تنكسر أبدًا. ويختار `pos="over|under|right"` الجهة. والصيغة المختصرة `{紅樓|hóng|lóu}` (قراءة لكل `|`) أو `{紅樓|hónglóu}` (قراءة واحدة للأساس كله) تُقرأ على النحو نفسه، ولكن فقط حين يحتوي الأساس حرفًا من الهان أو الكانا أو البوبوموفو، وخارج الصيغ الرياضية والشيفرة والسمات، لذا تبقى `{x|x>0}` في النثر اللاتيني نصًا. والشرطة المائلة العكسية قبل القوس المعقوف أو الخط العمودي تُبقي الصيني منهما نصًا: `{紅|hóng}` و`{紅\|hóng}` تطبعان `{紅|hóng}`. والأساس الذي يفتح سطرًا أو يغلقه يُحاذى إلى ذلك الطرف مع قراءته.
- **`:warichu[note]`** تُنضّد تعليقًا (双行夹注) في صفّين بنصف حجم النص داخل السطر، ويُقرأ الصف الأعلى أولًا (الأيمن في النص العمودي). والتعليق الطويل يملأ ما بقي من السطر ويستمر في السطر أو العمود أو الصفحة التالية. ويلفّه `open` و`close` بقوسين بحجم النص؛ ويحدّد `cjk.warichu` الحجم واللون والقوسين الافتراضيين. والتعليق المكتوب بالحروف اللاتينية ينكسر بين كلماته.

لا تتغير خطوة السطر أبدًا: تسكن العلامات والقراءات في تباعد الأسطر، ويحذّر البناء حين تكون الفجوة بين أسطر الفقرة أضيق من أن تتسع لها (`cjkMarksExceedLeading`، `rubyExceedsLeading`)، وحين لا تتسع العلامات تحت سطر والقراءات فوق السطر التالي في الفجوة التي يتقاسمانها، في فقرة واحدة أو عبر فقرتين. امنح الفقرات المشروحة نمط فقرة بتباعد أسطر أكبر. تُرسم العلامات والقراءات والتعليقات في الفقرات والعناوين وعناصر القوائم والاقتباسات الكتلية والإطارات؛ أما في التعليقات وخلايا الجداول والحواشي، وفي الترويسات والتصاميم، فيُطبع النص بدونها. ومع `cjk.bookTitleMark: 'brackets'` يكون قوسا العنوان 《》 من علامات ترقيم النص: تحتفظ بهما التعليقات والخلايا والحواشي وصفوف المحتويات والإشارات المرجعية ومداخل الفهرس. انظر [الإعدادات › العلامات والقراءات والتعليقات السطرية](/ar/docs/configuration#العلامات-والروبي-والواريتشو).

### اتجاه النص في الترميز

يجري المستند في الاتجاه الذي تقتضيه لغته `locale` (`direction` في الإعدادات: من اليمين إلى اليسار للعربية والفارسية والأردية والعبرية). وفي داخله يحدّد الترميز اتجاه الكتلة أو المقطع النصي، لاقتباس إنجليزي في كتاب عربي أو عربي في كتاب إنجليزي.

- **العنوان أو الحاوية**: `{dir=ltr}` أو `{dir=rtl}` في سماته، `# Introduction {dir=ltr}`، `:::paragraphs{dir=ltr}`، `:::callout{dir=rtl}`. تأخذ كل كتلة داخل الحاوية هذا الاتجاه، حتى حاوية متداخلة أو عنوان يحدّد اتجاهًا آخر. والفقرة العادية أو القائمة أو الاقتباس لا سمات لها: لفّها في `:::paragraphs{dir=…}`. وتُتجاهل القيم الأخرى. وسمة `lang` في الحاوية (`:::paragraphs{dir=ltr lang=en}`) تسمّي لغة الكتل التي بداخلها بالطريقة نفسها: تُرقَّم قوائمها المرتّبة بأرقام تلك اللغة.
- **المقطع النصي**: `:ltr[…]` و`:rtl[…]` تعزلان نصهما (LRI…PDI وRLI…PDI في خوارزمية Unicode ثنائية الاتجاه): يُرتَّب في داخله، وترى الفقرة المحيطة به حرفًا محايدًا واحدًا. ويوسم `{lang=…}` لغة المقطع في HTML وفي PDF. وعلامة الحاشية أو `:ref` أو الصيغة الرياضية داخله جزء من المقطع المعزول، والمقاطع المعزولة تتداخل.

```markdown
:::paragraphs{dir=ltr}
The opening of the *Nights* in Lane's translation.
:::

ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩.
```

الكتلة المنضّدة خلاف اتجاه المستند تحتفظ بجهة بدايتها: تنتقل إزاحتها وعلامات قوائمها والطرف الملاصق لسطرها الأخير إلى الجهة التي يبدأ منها نصها. استعمل العزل حين ينتهي عنوان لاتيني بحرف محايد (نقطة، قوس) كان سينضمّ لولا ذلك إلى العربية المحيطة به. وتُحترم محارف التحكم في Unicode نفسها أيضًا (U+2066–2069، U+202A–202E، U+200E، U+200F، U+061C). وفي محرّر Sandbox يجري كل سطر في اتجاه أول حرف فيه. انظر [الإخراج العربي](/ar/docs/arabic-layout#الاتجاه-وخوارزمية-النص-ثنائي-الاتجاه).

## الحواشي السفلية

للحاشية السفلية جزآن: العلامة `[^id]` حيث يُحال إلى الحاشية، والتعريف، وهو فقرة مستقلة تبدأ بـ`[^id]:` في أي موضع من الفصل.

```md
The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.

[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.
```

- **العلامة.** يطبع `[^id]` رقم الحاشية حرفًا فوقيًا ملتصقًا بالكلمة التي قبله (اكتبه بعد علامة الترقيم، كما في المثال). ويقبل المعرّف الحروف والأرقام و`-` و`_` و`.` و`:`. وتعمل العلامة في الفقرات وعناصر القوائم والاقتباسات الكتلية والإطارات؛ أما في العناوين والتعليقات وخلايا الجداول فتُطبع كما كُتبت.
- **التعريف.** فقرة تبدأ بـ`[^id]:`؛ يمتد نصها حتى السطر الفارغ التالي ويأخذ العلامات المضمّنة المعتادة (العريض، والمائل، والروابط، و`:ref`، والصيغ الرياضية، والشارات). وتغادر التعريفات التدفق أينما كُتبت، فيمكن أن تقع تحت الفقرة التي تحيل إليها أو أن تُجمع كلها في آخر الفصل. والغلبة لأول تعريف للمعرّف.
- **الأرقام.** تُرقَّم الحواشي بترتيب أول إحالة إليها، ويبدأ الترقيم من جديد في كل فصل (عنوان من المستوى 1، وكل مستند في الكتاب)؛ والحاشية المحال إليها مرتين تحتفظ برقمها الأول وتُنضَّد مرة واحدة. ويجعل `footnotes.numbering: 'document'` الترقيم متصلًا عبر الكتاب، و`'page'` يبدؤه من جديد في كل صفحة، كما تفعل الكتب الصينية؛ ويكتب `footnotes.numberFormat: 'circled-decimal'` ① ② ③ على خط الأساس.
- **موضع الحاشية.** افتراضيًا في أسفل العمود الذي يحوي السطر المحيل إليها، تحت خط قصير: يتقاسم السطر وحاشيته العمود دائمًا، والسطر الذي لا تتسع حاشيته ينتقل معها. وفي الإخراج ذي العمود الواحد يكون ذلك أسفل الصفحة. ويُنضّد `footnotes.placement: 'chapterEnd'` حواشي الفصل كلها بعد آخر كتلة فيه بدلًا من ذلك، افتراضيًا في أسفل العمود الذي تُختم به. انظر [الحواشي السفلية](/ar/docs/configuration#الحواشي-السفلية) في مرجع الإعدادات للأحجام والخط والمسافات.
- **الفحوص.** العلامة التي لا تعريف لها (`undefinedFootnote`) تطبع رقمها فوق حاشية فارغة؛ والتعريف الذي لا تحيل إليه أي علامة (`unusedFootnote`) لا يُنضَّد. وتعرض Sandbox الحالتين في لوحة الفحوص.

## الإحالات والمراسي

تسمّي الإحالة (cross-reference) موضعًا في الكتاب وتطبع رقمه أو عنوانه أو صفحته: *انظر القسم 3.2*، *كما يشرح الفصل 4*، *في ص. 112*. وتتبع الكلماتُ والأرقام النصَّ، فنقل قسم أو إعادة ترقيم الفصول أو إعادة تدفق الكتاب يحدّث كل إحالة. وفي PDF وHTML ومعاينات Sandbox تكون كل إحالة رابطًا: نقرة تأخذ القارئ إلى هدفها، ولو في فصل آخر.

**المراسي.** تحتاج الإحالة إلى شيء تشير إليه:

- **عنوان** له معرّف: `## Method {#sec-method}` (صيغة Pandoc؛ ويعمل `id="sec-method"` أيضًا).
- **إطار أو حاوية أخرى** تُفتح بمعرّف: `:::callout{#box-safety title="Safety"}`.
- **نقطة في النص**: يضع `:anchor{#key-idea}` مرساة (anchor) غير مرئية؛ ويحتفظ `[the key idea]{#key-idea}` بكلماته ويسمّيها.

يقبل المعرّف الحروف والأرقام و`-` و`_` و`.` و`:`. ويجب أن يكون فريدًا في الكتاب: تعرض لوحة الفحوص المعرّف الموضوع مرتين (`duplicateAnchor`)، وتصل الإحالات إلى أول موضع له.

**الإحالات.** يسمّي `:ref{id="…"}` المرساة كما يسمّي شكلًا أو جدولًا:

```md
## Method {#sec-method}

The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.
```

| `style` | ما يطبعه |
| --- | --- |
| *(لا شيء)* | العنوان المرقّم بكلمته ورقمه (*القسم 3.2*، *الفصل 4*)، والعنوان غير المرقّم بعنوانه، والمرساة بنصها |
| `number` | الرقم وحده (*3.2*) |
| `title` | عنوان العنوان، أو نص المرساة، أو `title` الإطار |
| `page` | الصفحة التي وقع فيها (*ص. 112*) |
| `pageNumber` | رقم الصفحة وحده (*112*) |

يطبع `text="…"` كلماتك أنت ويبقى رابطًا؛ ويبدأ `case=capitalize` التسمية بحرف كبير (*Section 3.2* في أول الجملة). وتتبع الكلمات لغة المستند (*sección 3.2*، *第3.2节*، *S. 112*) ويمكن تغييرها في [الإحالات](/ar/docs/configuration#الإحالات-المرجعية) في الإعدادات؛ ورقم العنوان الذي يكتبه قالبه بالحروف أصلًا (*Chapter 4*، *第四章*) يُطبع كما هو.

**الإحالات إلى الصفحات** لا تُعرف إلا بعد إخراج الكتاب. فيعيد المحرّك إخراج المستند بصفحات المرور السابق حتى تثبت، كما يفعل مع المحتويات؛ وإلى ذلك الحين تطبع الصفحة *?*.

**pandoc-crossref.** النص المكتوب لـpandoc-crossref يُقرأ على النحو نفسه: `@sec:method`، و`[@fig:map]`، و`[-@tbl:data]` للرقم وحده. وقد تكون البادئة (`sec`، `fig`، `tbl`، `eq`، `lst`) جزءًا من المعرّف (`{#sec:method}`) أو محذوفة منه (`{#method}`). وتبقى `@` الملتصقة بكلمة، كما في عنوان البريد الإلكتروني، نصًا.

الإحالة إلى معرّف لا يضعه شيء تطبع *?* وتعرضها لوحة الفحوص (`unknownResourceId`). وفي محرّر Sandbox يعرض `@` أشكال الكتاب وجداوله وعناوينه ذات المعرّفات ومراسيه.

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

اكتب الاستشهادات كما يقرؤها Pandoc، واحفظ المراجع في المستند، واختر نمط الاستشهاد في الإعدادات: الانتقال من APA إلى IEEE، أو إلى حواشي Chicago، يغيّر إعداد النمط لا النص. ويرتبط كل استشهاد بمدخله في قائمة المراجع.

### الاستشهاد

```md
As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.
```

- **`[@key]`** يستشهد بين قوسين؛ وتوضع الأعمال المتعددة في زوج واحد من الأقواس المربعة، مفصولة بـ`;`.
- **محدِّد الموضع:** بعد فاصلة، `p. 33`، `pp. 4–6`، `chap. 2`، `sec. IV`، `fig. 3`، `vol. 2`، `n. 12`، `l. 4`، `§ 4.2`؛ والعدد المجرد صفحة. وتعمل الكلمات الإسبانية (`pág.`، `cap.`) والصينية (`页`، `章`) أيضًا.
- **البادئة واللاحقة:** نص قبل `@` (`see`) وبعد محدِّد الموضع (`, emphasis added`).
- **`[-@key]`** يُسقط المؤلف، للجملة التي تسمّي المؤلف أصلًا.
- **`@key`** يستشهد داخل الجملة (*García (2020)*)؛ ويضيف `@key [p. 4]` محدِّد موضع.
- تبقى نصًا كلٌّ من `@` الملتصقة بحرف أو رقم (عنوان بريد إلكتروني)، و`@` في الشيفرة المضمّنة، و`\@`. والاستشهاد الذي لا مرجع له في الكتاب يُطبع كما كُتب، فيُقرأ المستند الخالي من المراجع كما كان. وفي الاستشهاد بعدة أعمال، يُطبع المفتاح الذي لا يعرّفه أي مرجع بالعريض بعد الأخرى (`(Glen, 1955) **@nye1953**`)، فيظهر العمل المفقود على الصفحة كما يظهر بين التحذيرات. والنقطتان بعد الاستشهاد نص: `[@french2018]: the land…`.
- في النص الصيني والياباني والكوري يتبع الاستشهادُ الحرفَ الأخير بلا مسافة (`周明远@zhou2019认为`)، ويأخذ استشهاد المؤلف والتاريخ علامات الترقيم كاملة العرض من النص المحيط به: `（施雅风等，1988；刘时银等，2015）`.

### المراجع

تُكتب المراجع في المستند، بصيغة CSL (نموذج البيانات في Zotero وPandoc):

```md
---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---
```

أو في كتلة `:::references`، بصيغة BibTeX (تصدير من Zotero أو JabRef أو Google Scholar) أو CSL-JSON أو CSL-YAML:

```md
:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::
```

لا تطبع الكتلة شيئًا. ويسرد `nocite` أعمالًا دون الاستشهاد بها (`@*`: كلها). وفي الكتاب، تُحتسب المراجع المكتوبة في أي فصل للكتاب كله.

### قائمة المراجع

يُنضّد `:::bibliography` قائمة الأعمال المستشهد بها في موضعه؛ ومن دونه تأتي القائمة بعد الفصل الأخير، بعنوان بلغة المستند (*References*، *Referencias*، *参考文献*). ويغيّر `:::bibliography{title="Works cited"}` العنوان، ويحذفه `title=""`؛ ويسرد `scope=chapter` الأعمال التي يستشهد بها الفصل (لكتاب جماعي محرَّر). وكل مدخل مرساة (`ref-<key>`)، فيصل إليه رابط Markdown إلى `#ref-garcia2020`، ويسمه PDF بالوسم `BibEntry`.

### الأنماط

يقرّر النمط ما يقوله الاستشهاد والمدخل. الأنماط المضمّنة مسرودة أدناه؛ ويمكن تحميل أي نمط CSL آخر (يضم مستودع أنماط Zotero أكثر من عشرة آلاف) من ملف `.csl` الخاص به في **الإعدادات › الاستشهادات**.

| `citations.style` | الاسم | النظام |
| --- | --- | --- |
| `apa` | APA 7 | المؤلف والتاريخ |
| `chicago-author-date` | Chicago (المؤلف والتاريخ) | المؤلف والتاريخ |
| `harvard-cite-them-right` | Harvard | المؤلف والتاريخ |
| `iso690-author-date-en`، `iso690-author-date-es` | ISO 690 | المؤلف والتاريخ |
| `china-national-standard-gb-t-7714-2025-author-date` | GB/T 7714—2025 著者-出版年 | المؤلف والتاريخ |
| `china-national-standard-gb-t-7714-2015-author-date` | GB/T 7714—2015 著者-出版年 | المؤلف والتاريخ |
| `modern-language-association` | MLA 9 | المؤلف والصفحة |
| `ieee` | IEEE | مرقّم |
| `elsevier-vancouver` | Vancouver | مرقّم |
| `american-medical-association` | AMA | مرقّم |
| `nature` | Nature | مرقّم |
| `iso690-numeric-en` | ISO 690 | مرقّم |
| `china-national-standard-gb-t-7714-2025-numeric` | GB/T 7714—2025 顺序编码 | مرقّم |
| `china-national-standard-gb-t-7714-2015-numeric` | GB/T 7714—2015 顺序编码 | مرقّم |
| `chicago-notes-bibliography` | Chicago (الحواشي) | الحواشي |
| `oscola` | OSCOLA | الحواشي |
| `china-national-standard-gb-t-7714-2025-note` | GB/T 7714—2025 注释 | الحواشي |
| `china-national-standard-gb-t-7714-2015-note` | GB/T 7714—2015 注释 | الحواشي |

مع **نمط الحواشي** يصير كل استشهاد حاشية سفلية، توضع وتُرقَّم كما تقول إعدادات الحواشي السفلية؛ وتأخذ الاستشهادات اللاحقة بالعمل نفسه صيغة مختصرة. وفي النص الصيني يُنضّد `citations.notes: 'warichu'` هذه الحواشي تعليقات من صفّين داخل السطر (夹注)؛ والحاشية التي تليها علامة صينية (`，`، `。`) تُسقط نقطتها الخاصة.

**الصينية.** تكتب أنماط GB/T 7714-2015 رموز نوع الوثيقة (`[M]`، `[J]`، `[D]`، `[EB/OL]`)، وتُبقي الأسماء الصينية كاملة، وتكتب `等` بعد ثلاثة مؤلفين لعمل صيني و`et al.` بعد مؤلفي عمل غربي، وتختار بحسب `language` كل عمل. وفي النص العمودي يقف الرقم الفوقي على يمين حرفه؛ ويكتب `citations.marker: 'corner'` الصيغة `〔1〕`، التي تبقى قائمة.

**المحرّك.** تُنسَّق الاستشهادات بالحزمة `postext-citeproc` (citeproc-js وأنماط CSL). تحمّلها Sandbox للمستندات التي فيها استشهادات؛ وفي شيفرتك أنت، سجّلها قبل الإخراج:

```ts
import 'postext-citeproc/register';
```

تعرض لوحة الفحوص المفتاح الذي لا يعرّفه أي مرجع (`unknownCitationKey`) وكتلة المراجع التي تتعذّر قراءتها (`referencesUnreadable`).

## الفهرس الأبجدي

يسرد الفهرس الأبجدي (back-of-book index) مصطلحات الكتاب مع الصفحات التي تظهر فيها. علّم كل مصطلح حيث يناقشه النص، واطبع الفهرس بـ`:::index` في موضعه، وهو عادةً فصل مستقل في النهاية. ويجد المحرّك صفحة كل علامة بعد الإخراج، فتتبع الأرقامُ النصَّ: أضف فقرة، أو انقل فصلًا، أو غيّر حدّ القص، فيطبع الفهرس الصفحات الجديدة.

```md
Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}

# Index {style="index"}

:::index
```

### علامات الفهرس

- **`:index[text]`** تطبع `text` وتُدرجه تحت كلماته نفسها. والعلامات المضمّنة داخلها تُطبع وتُسقط من المدخل. والسمات بعد القوس تُدرجه في موضع آخر: `:index[iron deficiency]{term="Anaemia!iron-deficiency"}`.
- **`:index{term="…"}`** لا تطبع شيئًا. تأخذ العلامة صفحة الكلمة المكتوبة قبلها مباشرة في سطرها، أو صفحة الكلمة التي بعدها إذا افتتحت سطرًا. ويُحذف السطر الذي لا يحوي إلا علامات، فلا تقسم العلامة الواقعة في سطر مستقل فقرةً ولا تضيف مسافة أبدًا.
- **المواضع.** الفقرات والعناوين وعناصر القوائم والاقتباسات الكتلية والإطارات وتعريفات الحواشي السفلية. أما في التعليقات وخلايا الجداول وعناصر التصميم فتُطبع العلامة كما كُتبت. وداخل الشيفرة المضمّنة، وبعد الشرطة المائلة العكسية (`\:index`)، تكون نصًا.

| السمة | الأثر |
| --- | --- |
| `term` | المدخل، ومستوياته مفصولة بـ`!`: يُدرج `term="Heart!valves!mitral"` الصفحة تحت *mitral*، وهو مدخل فرعي من *valves* تحت *Heart*. وقد يحمل المستوى علامات مضمّنة (`term="*Escherichia coli*"`)؛ ويُرتَّب من دونها. ومن دون `term` تستعمل `:index[text]` نصها. |
| `sub` | مستوى يُضاف بعد `term`: `term="Heart" sub="valves"` هو `term="Heart!valves"`. |
| `sort` | مفتاح ترتيب المستوى الأخير حين ينبغي أن يُرتَّب بحروف أخرى: `:index[St Kilda]{sort="Saint Kilda"}`، `term="20th century" sort="twentieth century"`. والفهرس الصيني يُرتّب ويُجمّع بحسب القراءة التي يعطيها المرتِّب (collator) للحرف. وللحرف متعدد القراءات المقروء على الوجه الآخر، اكتب المفتاح بحروف ليس لها إلا القراءة التي تريدها: `:index[重阳]{sort="崇阳"}` يُدرج 重阳 تحت C، بين 程 و崔، لا تحت Z. ومفتاح البينيين (`sort="chong yang"`) يصل إلى C أيضًا، لكنه يُرتَّب بعد كل مداخلها الصينية، لأن المرتِّب يضع الحروف اللاتينية بعد الحروف الصينية (انظر [الإعدادات › الفهرس الأبجدي](/ar/docs/configuration#الفهرس-الأبجدي)، `groupBy`). |
| `main` | علَم: الموضع الرئيسي لمناقشة المصطلح. يُنضَّد رقم صفحته بالعريض (`index.main`). والصفحة المعلَّمة على الوجهين تكون عريضة. |
| `range` | `range="start"` و`range="end"`، بالمصطلح نفسه، تحدّان مناقشة تمتد على عدة صفحات: يطبع المدخل `34–37`. والبداية بلا نهاية، أو النهاية بلا بداية، تطبع صفحتها الوحيدة وتُطلق `indexRangeUnclosed`. |
| `see` | إحالة بدل رقم الصفحة: `:index{term="Cardiac insufficiency" see="Heart failure"}` تطبع *Cardiac insufficiency. See Heart failure*. ومستويات الهدف مفصولة بـ`!` وتُطبع بنقطتين (*See Heart: valves*). والهدف الذي ليس مدخلًا في الفهرس يُطلق `indexSeeUnknown`. |
| `seealso` | إحالة بعد أرقام صفحات المدخل: *Heart, 12, 40. See also Circulation*. وتُحتسب صفحة العلامة نفسها كصفحة أي علامة أخرى، فتستطيع علامة واحدة أن تفهرس مقطعًا وتشير إلى مدخل ذي صلة؛ أما علامة `see` فلا تضيف صفحة. |
| `index` | اسم فهرس مستقل: `index="names"` يُدرج العلامة في الفهرس الذي تطبعه `:::index{index="names"}`، لا في الفهرس الرئيسي. |

العلامة التي لا مصطلح لها (`:index{}` أو `:index{see="…"}` وحدها) لا تفهرس شيئًا وتُطلق `indexMarkInvalid`.

### طباعة الفهرس

يطبع `:::index` الفهرس الرئيسي في موضعه، و`:::index{index="names"}` فهرسًا مسمّى. ويتمدّد التوجيه إلى كتل عادية، كتلة لكل مدخل، تجري عبر الأعمدة والصفحات كالنص: تحت عنوان يحدّد [نمطُ عنوانه](/ar/docs/configuration#أنماط-العناوين) `layout` من عمودين، يعطي الفهرس المعتاد ذا العمودين. والنقر على مدخل ينقلك إلى سطر التوجيه.

```md
# Index of names {style="index"}

:::index{index="names"}

# Index of subjects {style="index"}

:::index
```

- **الترتيب.** تُرتَّب المداخل بالترتيب الأبجدي للغة المستند (`locale`، أو `index.locale`): الحرف المشكول بعلامة يُدرج مع حرفه الأساسي (*Árbol* تحت A)، وفي الإسبانية يأتي *ñ* بعد *n*، تحت رأس خاص به. وتأتي أولًا المداخل التي تبدأ برمز، ثم التي تبدأ برقم، ثم الحروف. وتُرتَّب المداخل الفرعية بالطريقة نفسها تحت مدخلها، مزاحةً خطوة لكل مستوى.
- **المجموعات.** كل حرف أول جديد يفتح مجموعة: رأس حرف (`index.groups`) وسطر من المسافة فوقه (لا شيء فوق المجموعة الأولى). ويُنضَّد الرأس في كتلة واحدة مع أول مدخل في المجموعة، فلا يختم عمودًا وحده أبدًا؛ والمدخل الذي لا صفحة له (الذي لا يفعل إلا أن يترأس مداخله الفرعية) يُنضَّد مع أول مدخل فرعي له للسبب نفسه.
- **أرقام الصفحات.** التسميات التي تطبعها الصفحات، بما فيها الرومانية في الصفحات التمهيدية. تُرتَّب صفحات المدخل وتُسرد كل منها مرة واحدة؛ وتنضمّ الصفحات المتتالية في مدى (`12–14`، `index.mergeRanges`)، والصفحة الواقعة داخل مدى للمدخل نفسه تُطوى فيه (والصفحة الرئيسية هناك تجعل المدى عريضًا)، ويختصر `index.rangeFormat: 'chicago'` الرقم الثاني (`234–37`). وتبقى الصفحات العريضة (الرئيسية) منفصلة. وفي PDF يرتبط كل رقم بصفحته.
- **الإحالات** تختم المدخل: *Term. See Target* حين لا تكون للمدخل صفحات، و*Term, 12. See also Target* حين تكون له. وتتبع التسميات لغة المستند (*See*، *Véase*…) ويمكن ضبطها في `index.see`.
- **الكتب.** في الكتاب المُخرَج فصلًا فصلًا (Sandbox، `buildBundle`) يتلقى الفصل الذي يطبع الفهرس علامات كل الفصول مع صفحاتها، ولا يُعاد إخراجه إلا حين تتحرك إحداها. والمستند الذي يحوي علاماته وفهرسه معًا يُعاد إخراجه حتى تثبت الأرقام، كما مع `:::toc`.

انظر [الفهرس الأبجدي](/ar/docs/configuration#الفهرس-الأبجدي) في مرجع الإعدادات للتنسيق الطباعي والإزاحات والفواصل.

## الصيغ الرياضية

دعم الرياضيات جزء أصيل من صيغة المستند. يحلّل Postext `$…$` للصيغ المضمّنة و`$$…$$` لصيغ العرض (الكتلية)، ويرسمها عبر [MathJax](https://www.mathjax.org/) في وضع SVG. والمسارات المتجهية نفسها تغذّي المُخرِجات الثلاثة، فتتطابق معاينة Canvas وتصدير HTML ومخرجات PDF بكسلًا ببكسل — ويبقى PDF متجهيًا بالكامل مهما كان مستوى التكبير.

- **المضمّنة:** `$…$`. يُتعرَّف عليها داخل أي كتلة نصية (فقرة، عنوان، اقتباس كتلي، عنصر قائمة). تُسهم في السطر بصندوق واحد ذرّي غير قابل للكسر؛ ويعاملها Knuth-Plass ككلمة لا يجوز تقسيمها. وإذا كان ارتفاع الصيغة الطبيعي سيكسر صندوق السطر صُغّرت بانتظام لتُحفظ شبكة خطوط الأساس — والتعابير الطويلة جدًا مكانها وضع العرض.
- **العرض:** `$$…$$`. إما في سطر مستقل (`$$\int_0^1 x^2\,dx$$`) وإما مسيّجة عبر عدة أسطر بعلامتي `$$` في سطرين مستقلين. تُرسم في وسط العمود وتُثبَّت على شبكة خطوط الأساس بهامشين علوي وسفلي قابلين للضبط (`math.marginTop`، `math.marginBottom`) — وهي آلية التصحيح نفسها تمامًا التي تستعملها العناوين، فتعود الفقرة التالية للصيغة إلى الشبكة.
- **النص المحيط بصيغة العرض:** صيغة العرض في سطر مستقل تقطع الفقرة ولو لم يكن فوقها سطر فارغ. والنص الذي قبلها فقرة تمهّد لها؛ والنص المكتوب مباشرة تحت `$$` الختامية، بلا سطر فارغ، يُكمل الفقرة المقطوعة ويُنضَّد بلا إزاحة للسطر الأول، كما ينضّد TeX عبارة «where …» بعد صيغة العرض. أما الصيغة المفصولة عن النص الذي فوقها بسطر فارغ (أو التالية لقائمة أو اقتباس أو عنوان) فلا تقطع شيئًا: النص بعدها فقرة جديدة، مُزاحة كالمعتاد، بسطر فارغ أو بدونه (ويجعلها `math.indentAfterDisplay: false` ملاصقة للحافة أيضًا). ولا يقطع الفقرةَ إلا عرضٌ كامل — صيغة واحدة في السطر، أو سياج `$$` يُغلق قبل السطر الفارغ التالي؛ أما سطر مثل `$$a$$ and $$b$$` فيبقى نصًا. ويُبقي `math.keepWithLeadIn` الصيغة في عمود السطر الذي يقدّم لها. (حتى postext 1.4 كان سطر `$$…$$` الذي ليس فوقه سطر فارغ يُقرأ جزءًا من الفقرة ويُطبع كما كُتب.)
- **أرقام المعادلات:** يرقّم `\tag{…}` صيغة العرض: تمتد على عرض العمود (أو العرض الداخلي للإطار)، والمعادلة في الوسط ورقمها ملاصق للحافة اليمنى في سطره — في كل صف موسوم من `align`. ويطبع `\tag*{…}` التسمية بلا أقواس. ولا يُرقَّم إلا ما وُسم صراحةً.
- **التهريب:** `\$` علامة دولار حرفية. لا تُحلَّل الرياضيات في التعليقات وخلايا الجداول والحواشي والشارات، فتُطبع `$` هناك كما هي؛ ويطبع `\$` علامة دولار هناك أيضًا، فيُقرأ النص المهرَّب نفسه على النحو نفسه في المتن وفي الجدول. ومحدِّدات `$` أو `$$` غير المتطابقة تُنتج مدخل `unclosedMath` في لوحة الفحوص في Sandbox مع مرساة إلى المصدر تنقلك إليه بالنقر.
- **الأخطاء:** مصدر TeX الذي يرفضه MathJax (وحدات ماكرو غير معرّفة، أخطاء صياغة) يظهر تحذيرًا من نوع `invalidMath`. وتُستبدل الصيغة بعنصر نائب أحمر صغير لتبقى هندسة الإخراج صالحة.
- **الإعدادات:** يعرض القسم `math` من الإعدادات `enabled`، و`fontSizeScale` (نسبةً إلى حجم النص المحيط: عند 1.0 يكون em الصيغة الواحد بذلك الحجم — حجم المتن لصيغ العرض وللرياضيات المضمّنة في نص المتن؛ منذ postext 1.5، الذي ينضّد الصيغ أصغر بنحو 13% مما كان 1.4 ينضّدها، بينما تحتفظ الحزم وكتب Sandbox التي حفظها 1.4 بحجمها — انظر [حجم الصيغة](/ar/docs/configuration#الصيغ-الرياضية))، و`color` (يرث لون المتن إذا لم يُحدَّد)، وهامشي العرض.
- **المحرّك:** يُحمَّل MathJax عند الطلب. تشغّله Sandbox وعامل الإخراج بنفسيهما؛ وفي شيفرتك أنت، نفّذ `await initMathEngine()` قبل `buildDocument`، وإلا أُخرجت كل صيغة صندوقًا نائبًا رماديًا (انظر [تشغيل محرّك الرياضيات](/ar/docs/configuration#تشغيل-محرّك-الرياضيات)).

```md
The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants.

$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$
```

صيغة في وسط جملة، والجملة تستمر بعدها بلا إزاحة:

```md
For a pendulum of length $L$ the period is
$$T_0 = 2\pi\sqrt{L/g}$$
where $g$ is the acceleration of free fall.
```

## الموارد

لا تُكتب الصور ورسوم SVG والجداول داخل النص. تُعرَّف مرة واحدة بوصفها **موارد** (تديرها [لوحة الموارد](/ar/docs/sandbox#لوحة-الموارد) في Sandbox، وفيها رفع الصور وملفات SVG، ومحرّر جداول تفاعلي، وتحرير التعليقات والمواضع)، ثم تُربط بنصّك عبر معرّفها. **تكفي الإحالة إلى المورد لإدراجه**: تذكره مرة واحدة بإحالة داخل السطر `:ref{id="…"}`، فيُعوِّم المحرّك الشكل أو الجدول إلى أول موضع شاغر بعد تلك الإحالة، كأسفل العمود الذي ذكرته فيه، أو أعلى العمود التالي، أو شريط في الصفحة التالية، كما يفعل المنضّد في المطبعة. ولا تضعه مرة ثانية.

الصيغتان أدناه صياغة جديدة كليًا لا تتعارض مع CommonMark، فيبقى المستند الذي يستعملهما مقروءًا نصًا عاديًا في أي عارض Markdown آخر.

### الإحالة داخل السطر (الصيغة الأساسية)

أحِل إلى مورد من داخل النص بالصيغة `:ref{id="…"}`. الإحالة الأولى **تُدرج** المورد (فيوضع في الصفحة) وتعرض رقمه المحسوب في آن واحد، مسبوقًا افتراضيًا بالتسمية المختصرة لنوعه:

```md
As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.
```

وتظهر هكذا: *As shown in Fig. 1.7, the lantern room sits above the gallery.* ويطفو الرسم نفسه إلى أقرب موضع شاغر بعد الجملة (أسفل هذا العمود، أو أعلى العمود التالي، أو شريط في الصفحة التالية)، بينما تتدفق هذه الجملة والنص الذي يليها دون انقطاع.

لا ينقطع النص الجاري أبدًا عند نقطة الإحالة. أما المكان الذي يستقر فيه المورد (أول موضع شاغر، أو موضع علوي أو سفلي فقط؛ داخل عمود واحد أو بعرض الصفحة كله) فيحكمه **موضعه** (انظر [الموضع](#الموضع) أدناه)، ويحكمه كذلك المكان الذي تذكره فيه: يبدأ البحث مباشرة بعد الإحالة.

### التضمين في كتلة (اختياري، لوضع صريح داخل التدفق)

قد تريد أحيانًا أن يقع المورد في نقطة محددة من التدفق بدل أن يطفو. ألغِ التعويم بإعطاء المورد `placement.position: "here"` وتضمينه بالصيغة `::resource{id="…"}` في سطر مستقل:

```md
Here is the floor plan we discussed.

::resource{id="lighthouse-diagram"}

The keeper's quarters occupy the eastern wing.
```

لا حاجة إلى التوجيه `::resource` مع مورد عائم، فقد وضعته `:ref` من قبل، ويُعامل `::resource` الزائد للمعرّف نفسه إحالةً أخرى ببساطة، لا نسخة ثانية. ولا يعرض `::resource` المورد داخل التدفق إلا إذا كان موضعه المحسوم `"here"`. ويحتفظ المورد المضمّن بمسافة سطر فوقه (فجوة العنصر العائم) كما يفعل العنصر العائم، ما لم تطلب الكتلة التي قبله أكثر من ذلك. وفي النص الجاري يحتفظ بالمسافة نفسها تحته؛ ثم يعود النص الذي يليه إلى شبكة خطوط الأساس، وقد يضيف ذلك ما يصل إلى سطر آخر. وإذا تلاه مباشرة عنوان أو قائمة أو إطار أو مورد مضمّن آخر، تقاسمت تلك المسافة مع المسافة التي فوقه: يُطبَّق الأكبر منهما، لا كلاهما. (حتى postext 1.4 لم تكن المسافة تحته سوى ما يتركه الالتصاق بالشبكة، من لا شيء إلى سطر كامل؛ ويحافظ `layout.inlineResourceGap: 'above'` على تلك القاعدة، وتُقرأ بها الكتب المحفوظة قبل 1.5.) وداخل الإطار (`:::callout`) يحتفظ المورد بالمسافة نفسها، أي سطر من نص الإطار نفسه فوقه، وتحته أيضًا مع `'around'`؛ وفي أعلى الإطار أو أسفله تفصله الحشوة بدلًا من ذلك. (حتى postext 1.4 كان يلتصق بنص الإطار مباشرة؛ ويحافظ `layout.inlineResourceGapInBoxes: false` على ذلك، وتُقرأ به الكتب المحفوظة قبل 1.5 التي تضمّن أطرها موردًا.)

يجب أن يطابق `id` موردًا معرّفًا في لوحة الموارد. يرسم المحرّك المورد (صورة نقطية أو SVG أو جدول) وتعليقه تحته ذيلًا للشكل أو الجدول. ويتألف نص التعليق من `captionPrefix` لنوع المورد، والرقم المحسوب، والتعليق الخاص بالمورد، مثل **Figure 1.7. The original lighthouse plan.** وتحكم تنسيقه [الإعدادات › نمط التعليق](/ar/docs/configuration#نمط-التعليقات): تتشارك التسمية والوصف خطًا واحدًا وحجمًا واحدًا، بينما تحتفظ التسمية بإعدادات مستقلة للعريض والمائل واللون؛ والفجوة فوق التعليق `0.75em` افتراضيًا، والمحاذاة إلى اليسار. ويمكن أن يقع التعليق فوق المورد بدلًا من ذلك (`captionStyle.position: 'above'`، على مستوى المستند أو لكل نوع مورد)، على شريط ملوّن إن شئت. ويمكن أن يحمل المورد أيضًا `note`، وهو سطر قصير للمصدر أو الحقوق، بالتنسيق داخل السطر نفسه وعلامات `:ref` نفسها التي في التعليق، يُنضَّد بحجم أصغر تحت المورد (تحت التعليق حين يكون التعليق أسفله، وتحت جسم المورد حين يكون التعليق أعلاه) وينسَّق عبر `captionStyle.note`.

**فواصل الأسطر في التعليقات والملاحظات.** التعليق أو الملاحظة فقرة واحدة تُنضَّد بعرض موضعها، والسطر الجديد المكتوب فيها مسافة. لبدء سطر جديد، اكتب `\\`، وهو الفاصل الإجباري في العناوين، أو أنهِ السطر بشرطة مائلة عكسية، وهي الفاصل الصلب في Markdown: `¹ Measured at 20 °C. \\ ² Mean of three runs.` تضع كل حاشية من حواشي جدول عريض في سطر مستقل. يحتفظ السطر الذي يسبق الفاصل بعرضه الطبيعي ولا يُمدَّد إلى عرض السطر، ولا يُنتج فاصلان متتاليان سطرًا فارغًا (أما مسافة غير فاصلة بينهما فتُنتجه). وفي خلية الجدول يفعل `\\` ما يفعله السطر الجديد: يفتح فقرة جديدة؛ وتُحفظ إزاحة السطر الذي يليه، فتظل مسافتان في أوله تُدرجان بند القائمة في مستوى أعمق. وفي النص نفسه تكون الشرطتان المائلتان العكسيتان فاصلًا دائمًا، ولا سبيل إلى تهريبهما: لطباعتهما، ضعهما في شيفرة داخل السطر، حيث تُطبع الشرطات المائلة العكسية كما كُتبت. وفي وجهة الرابط تبقيان جزءًا من عنوان URL، وفي سمات التوجيه (`text` في `:ref`) جزءًا من القيمة؛ وداخل الشارة (chip)، التي تُنضَّد في سطر واحد، يكون الفاصل مسافة. (حتى postext 1.4 كانت الشرطتان تُطبعان، ولم يكن التعليق أو الملاحظة ينكسر إلا حيث ينتهي عرض السطر.)

ترسم موارد الجداول شبكتها الخاصة، وتُنسَّق عبر [الإعدادات › نمط الجدول](/ar/docs/configuration#نمط-الجداول): لخلايا المتن وخلايا الترويسة تنسيق مستقل تمامًا، وخلفية الترويسة `#f0f0f0` افتراضيًا، والحدود `0.75pt`، و`cellPadding` قيمته `0.375em`؛ وكل حقل لم يُضبط يرث من نص المتن. عروض الأعمدة جزء من الجدول نفسه: يحمل `TableModel.columnWidths` وزنًا نسبيًا واحدًا لكل عمود (`[2, 1, 1]` يمنح العمود الأول نصف العرض)؛ وإذا لم يُضبط، تقاسمت الأعمدة العرض بالتساوي. ويمكن أيضًا تنضيد الجدول بنمط مسمّى: يختار `table.styleId` واحدًا من `tableStyles` في المستند (انظر [الإعدادات › أنماط الجداول المسمّاة](/ar/docs/configuration#أنماط-الجداول-المسمّاة))، وترث حقوله غير المضبوطة من `tableStyle`؛ والمعرّف المجهول أو الغائب يُبقي على `tableStyle`.

تضع الخلية محتواها بالخاصية `TableCell.align` (`left`، `center`، `right`؛ وتبقى بنود القوائم محاذية لليسار) والخاصية `TableCell.verticalAlign` (`top`، وهي الافتراضية، أو `middle` أو `bottom`). تنقل المحاذاة الرأسية محتوى الخلية كله، أي الصورة والنص الذي تحتها بوصفهما وحدة واحدة، داخل خلية أطول منه: صف مدّته خلية مجاورة أطول، أو الصفوف التي يغطيها `rowSpan`. وتسري في كل المخرجات (Canvas وHTML وPDF)، وفي الجداول المدوّرة، وفي كل شريحة من جدول مقسوم على عدة صفحات. ويُضبط كلاهما لكل خلية من أزرار المحاذاة في شريط أدوات محرّر الجداول في Sandbox.

ويمكن أن تحتوي خلية الجدول صورة أيضًا. يسمّي `TableCell.image` موردًا من نوع صورة نقطية أو SVG بمعرّفه (`{ "resourceId": "fig-arm", "width": 0.7 }`): تُرسم الصورة داخل الخلية، دون ترقيم أو تعويم أو تعليق، بحيث تلائم العرض الداخلي للخلية (أو الكسر منه الذي يحدده `width`، وقيمته الافتراضية `1`) مع الحفاظ على نسبة أبعادها، وتُحاذى كما يُحاذى نص الخلية، ويجري أي نص في الخلية تحتها. ويزداد ارتفاع الصف ليتسع لها. وفي محرّر الجداول في Sandbox يختار زر الصورة في شريط الأدوات المورد للخلية النشطة، ويضبط حقل العرض الكسر. والمعرّف الذي لا يطابق أي مورد صورة يترك الخلية نصية فقط.

ويمكن أن تحمل الخلية تعبئتها الخاصة. `TableCell.background` قيمة لون (`{ "hex": "#c1dfd6", "model": "hex" }`، ويمكن ربطها بمُدخل في لوحة ألوان المستند عبر `paletteId`) تُطلى بدل خلفية الترويسة أو المتن في النمط؛ وبهذه الطريقة تظلّل مصفوفة التوافق خلاياها بالأخضر والأحمر والأصفر. ويضبطها محرّر الجداول في Sandbox من أداة التعبئة في شريط الأدوات. ولشرح دلالة هذه التعبئات، يقبل التعليق والملاحظة وأي كتلة نصية **عيّنة لون** داخل السطر: `:swatch{color="#c1dfd6"}` (قيمة hex، أو معرّف مُدخل في لوحة الألوان، مثل `:swatch{color="table-compatible"}`) تضع مربعًا صغيرًا على خط الأساس، بثلاثة أرباع حجم الخط، مملوءًا باللون ومحاطًا بإطار بلون النص، فيمكن أن تقرأ الملاحظة `:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible`. واللون الذي لا يُحسم إلى شيء يرسم إطارًا فارغًا. ويمكن أن تحمل قيمة hex قناة شفافية (`#rrggbbaa`، `#rgba`)، وتعمل ألوان `rgb()` / `rgba()` أيضًا، فيكون لتعبئة الخلية الشفافة مفتاح شفاف مطابق (انظر [الإعدادات › الشفافية](/ar/docs/configuration#الشفافية)).

ويمكن كذلك إعادة تلوين موارد SVG للطباعة بلون موضعي واحد عبر `diagramStyle.singleInk` (القيمة الافتراضية `false`). عند تفعيله، يُعاد تعيين كل لون في رسم SVG إلى درجة من `diagramStyle.inkColor` بحسب سطوعه (وقيمته الافتراضية لون لوحة الألوان الرئيسي، `#295AA3`)، فيصير الأبيض لون الورق والأسود الحبر كاملًا، فتُطبع الأشكال بأمانة حين يُطبع المستند بلون موضعي واحد. انظر [الإعدادات › نمط الرسوم التخطيطية](/ar/docs/configuration#نمط-المخططات).

التضمين المعيب (`id` مفقود أو فارغ، أو `id` غير محاط بعلامتي تنصيص أو محاط بعلامتي تنصيص مفردتين، أو سمات زائدة) لا يُرقّى إلى كتلة مورد؛ بل يُحلَّل فقرةً عادية ويبقى ظاهرًا في المخرجات. وكذلك سطر التضمين السليم الملتصق تحت سطر فقرة دون سطر فارغ بينهما: يُقرأ جزءًا من تلك الفقرة. وكلاهما يطلق تحذير `malformedEmbed`، وهو مُدخل **تضمين نُضِّد نصًا** في لوحة الفحوص في Sandbox.

تُتعرَّف الإحالات داخل السطر في أي كتلة نصية، أي الفقرات والعناوين والاقتباسات الكتلية وبنود القوائم، ويمكن أن تجاور العريض والمائل والشيفرة داخل السطر والرياضيات داخل السطر.

#### خيارات الإحالة

يقبل التوجيه `:ref` ثلاث سمات اختيارية، بأي ترتيب. تختار `style` طريقة عرض التسمية المحسوبة: `style="number"` يطبع الرقم مجردًا (`1.7`)، و`style="full"` يطبع الاسم الكامل للنوع مع الرقم (`Figure 1.7`)، وإذا لم تُضبط `style` استُعملت `shortLabel` للنوع مع الرقم (`Fig. 1.7`). وتغيّر `case` حالة الأحرف في جزء التسمية وحده، `lower` أو `upper` أو `capitalize`، ولا تمسّ الرقم. أما `text` فتجاوزٌ حرفي يحل محل أي تسمية محسوبة وله الأسبقية على `style` و`case` كلتيهما. خيارات العرض جنبًا إلى جنب:

| الصياغة | الناتج | ملاحظات |
| --- | --- | --- |
| `:ref{id="…"}` | `Fig. 1.7` | النمط الافتراضي: `shortLabel` للنوع يليها الرقم، تصل بينهما مسافة غير فاصلة فلا ينفصلان أبدًا عند التفاف السطر. |
| `:ref{id="…" style="number"}` | `1.7` | الرقم المحسوب مجردًا، دون تسمية. |
| `:ref{id="…" style="full"}` | `Figure 1.7` | الاسم الكامل للنوع `name` يليه الرقم. استعمله في بداية الجملة أو حيث يبدو الاختصار ركيكًا. |
| `:ref{id="…" case="lower"}` | `fig. 1.7` | يغيّر حالة أحرف التسمية وحدها: `lower` (`fig. 1.7`)، أو `upper` (`FIG. 1.7`)، أو `capitalize` (الحرف الأول كبير). ويجتمع مع `style="full"` (`figure 1.7`)؛ ولا يُمسّ الرقم أبدًا، وتُتجاهل القيمة غير المعروفة. |
| `:ref{id="…" text="see the plan"}` | `see the plan` | تجاوز صريح. يُستعمل النص المعطى حرفيًا بدل أي تسمية محسوبة، وهو مفيد للروابط داخل النص مثل «كما رأينا سابقًا». وعند وجود `text` تكون له الأسبقية على `style` و`case`. |

إذا سمّت `:ref` (أو `::resource`) معرّفًا لا يطابقه أي مورد، تعود التسمية إلى `?` (وتُطبع تسمية `text=` بدلًا منها، دون رقم أو رابط أيضًا) ويطلق Sandbox تحذير **مورد غير معروف**. ويسجّله المحرّك مُدخلًا من نوع `unknownResourceId` في `contentWarnings` الخاصة بالمستند، مع نطاق الإحالة في المصدر وصفحتها، وكذلك لإحالة `:ref` داخل تعليق أو ملاحظة أو خلية جدول لمورد يستعمله النص.

### الترقيم بحسب الإحالة الأولى

يُسند رقم المورد **أول مرة يُذكر فيها بترتيب القراءة**، سواء أكان هذا الذكر الأول تضمينًا في كتلة `::resource` أم إحالة داخل السطر `:ref`. ومن ثَمّ تطبع كل إحالة إلى المعرّف نفسه الرقم نفسه.

أي أن الأرقام تتبع ترتيب لقاء القارئ بالموارد، لا ترتيب إنشائها في اللوحة:

- إذا أحلت إلى شكل بـ`:ref` في المقدمة ولم تضمّنه (`::resource`) إلا بعد صفحتين، أخذ مع ذلك رقم المقدمة، لأن الإحالة جاءت أولًا.
- إدراج إحالة جديدة في موضع *أسبق* من المستند يعيد ترقيم كل ما بعدها تلقائيًا. فلا ترقيم يدوي تحتاج إلى مزامنته.

الترقيم خاص بكل نوع مورد، ويراعي نطاق إعادة الضبط وصيغة العدّاد لكل نوع؛ انظر [الإعدادات › أنواع الموارد](/ar/docs/configuration#أنواع-الموارد) لرموز القالب (`{h1}`، `{n}`)، و`resetOn`، و`counterFormat`.

لا يُعدّ إلا ما يحيل إليه النص: المورد الذي لا يرسمه إلا التصميم (عنصر صورة في صفحة افتتاح الفصل مثلًا) لا يأخذ رقمًا ويترك العدّاد على حاله. ويعدّ `{h1}` كل عنوان من المستوى 1 لا يكون نمطه `numbered: false`، حتى لو كان `numberingTemplate` فيه فارغًا، فالمقالة التي عنوانها هو عنوانها الوحيد من المستوى الأول ترقّم أشكالها 1.1، 1.2… افتراضيًا. وفي [الإعدادات › ما الذي يُرقَّم](/ar/docs/configuration#ما-الذي-يُرقَّم) القاعدتان كلتاهما والإعدادات اللازمة لـ Figure 1، 2….

### الموضع

لكل مورد **موضع** (placement) يحدد أين يستقر عنصره العائم، ويُحسم لكل مورد على حدة (من `placement` الخاص به)، ثم من `defaultPlacement` لنوعه، ثم من القيمة الافتراضية المدمجة `auto` / `column`:

| الحقل | القيم | المعنى |
| --- | --- | --- |
| `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"` (القيمة الافتراضية) يأخذ أول موضع شاغر بعد الإحالة، علويًا كان أو سفليًا؛ و`"top"` / `"bottom"` لا يقبلان إلا مواضع من ذلك النوع؛ و`"here"` يلغي التعويم ويضمّن المورد داخل التدفق عند التوجيه `::resource`. |
| `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | مورد أضيق من موضعه: `width` هو الكسر الذي يشغله من عرض العمود (أو الصفحة)، و`align` مكانه داخل الموضع (جدول صغير في وسط عموده؛ شريط بعرض الصفحة تمتد صورته على عمود واحد). والصورة الأضيق من موضعها، كصورة نقطية أصغر من العمود أو صورة صغّرها `layout.fitFiguresToPage`، تقع هناك أيضًا بحسب `align`، تحت تعليق يحتفظ بعرض الموضع. يسري ذلك على العناصر العائمة وعلى تضمينات `::resource` داخل التدفق على السواء. |
| `captionSide` | `true` · `false` | في تخطيط العمود ونصف الذي يُخصَّص فيه العمود الجانبي للعناصر العائمة (`layout.sideColumnRole: 'floats'`)، يُبقي العنصر العائم من نوع `"column"` ذو `captionSide` جسمه في العمود الرئيسي، ويُنضّد تعليقه (وملاحظته) في العمود الجانبي، محاذيًا لأعلى الشكل، أو لأسفله في العنصر العائم السفلي؛ ويتنازل العمود الجانبي عن ذلك الشريط. والصفحة التي ليس فيها هذا العمود تُبقي التعليق تحت الشكل. |
| `span` | `"column"` · `"page"` | يشغل عمودًا واحدًا، أو يقطع تدفق الأعمدة ويمتد بعرض المحتوى كاملًا عبر كل الأعمدة. وفي التخطيط ذي العمود الواحد تتطابق القيمتان. |
| `rotate` | `"ccw"` · `"cw"` | يُنضّد المورد مُدارًا ربع دورة، كجدول أفقي في كتاب عمودي. `"ccw"` يديره عكس عقارب الساعة، فيواجه أعلاه الحافة اليسرى للصفحة (ويدير القارئ الكتاب مع عقارب الساعة)، وهو العُرف المعتاد؛ و`"cw"` في الاتجاه الآخر. المورد المُدار عنصر عائم بعرض الصفحة دائمًا في صفحة مستقلة: يُخرَج على امتداد ارتفاع منطقة المحتوى، مقرَّبًا إلى الأدنى إلى أسطر كاملة من شبكة خطوط الأساس وناقصًا سطرًا واحدًا من المتن، وهو فجوة العنصر العائم التي يحتفظ بها كل شريط عائم (منطقة نص ارتفاعها 237 mm على شبكة 14 pt تسع 47 سطرًا، أي 232.1 mm، فيأخذ المورد 46 منها، أي 227.2 mm)، ويلتصق بالكعب حين تكون الهوامش متناظرة (وبالحافة اليسرى في غير ذلك)، والجدول الأعرض من صفحة واحدة يُقطع بين الصفوف ويُستأنف، مُدارًا، في الصفحات التالية مع تكرار ترويسته، تمامًا كالجدول القائم الأطول من صفحة. ويُصغَّر الشكل المُدار ليلائم الصفحة. ويُتجاهل هذا الحقل في التضمين داخل التدفق (`"here"`). |

يذهب العنصر العائم إلى **أول موضع شاغر بعد إحالته الأولى**، بترتيب القراءة: أسفل العمود الذي تقع فيه الإحالة، ثم أعلى العمود الفارغ التالي في الصفحة نفسها وأسفله، ثم أشرطة الصفحة التالية التي يفتحها التدفق (العنصر العائم بعرض الصفحة يأخذ أسفل الصفحة حين يبقى في كل عمود متسع له، وإلا فشريطًا في الصفحة التالية). والصفحة التي يفتحها شكل أو جدول مضمّن داخل التدفق تُحتسب أيضًا: العنصر العائم الذي ينتظر تلك الصفحة يأخذ رأسها، فوق الشكل أو الجدول، حين يتسع لهما معًا؛ وإن لم يتسع، احتفظ الشكل أو الجدول بالصفحة وانتظر العنصر العائم الصفحة التالية. وحتى postext 1.4 كانت هذه الصفحة تُتخطّى، فينتظر العنصر العائم الصفحة التي بعدها حتى لو اتسعت لهما. ولا يُصغَّر العنصر العائم أبدًا، ولا يستقر أبدًا قبل إحالته. وتظهر العناصر العائمة من سلسلة ترقيم واحدة بترتيب إحالاتها: الشكل الذي لا يجد مكانًا في صفحة يؤخّر الأشكال التي خلفه (والجدول المنتظر لا يؤخّر شكلًا، ولا العكس)، فلا يظهر الشكل 12 أبدًا قبل الشكل 11. أما الجدول الذي كان سينتظر فيُقطع بدلًا من ذلك: إذا عُرض عليه رأس عمود فارغ، أخذ الصفوف التي تتسع واستُؤنف في الموضع التالي، العمود المجاور أو الصفحة التالية، مع تكرار صفوف ترويسته (انظر `tableStyle.overflow`).

لا تخرج العناصر العائمة أبدًا من فصلها: عند صفحة افتتاح فصل (مستوى عنوان فيه `breakBefore` أو `span: 'page'`)، وعند `:::part`، وعند نمط إطار فيه `floatBarrier: true` (إطار «النقاط الرئيسية» الذي يختم الفصل)، وفي نهاية المستند، يوضع أولًا كل عنصر عائم لا يزال معلّقًا، في المواضع الشاغرة من الصفحة أو في صفحات تُفتح قبل الحدّ. والعنصر العائم الذي يحيل إليه الافتتاح نفسه أولًا (عنوان فصل يسمّي شكله)، أو الكتلة الأولى بعد `:::part`، ينتمي إلى الفصل الجديد: يستقر بعد ذلك السطر كأي عنصر آخر. وقد يأخذ عندئذ الشكل أو الجدول الذي طلب رأس صفحة أسفلَ الصفحة الختامية للفصل، تحت أعمدتها المتوازنة، بدل صفحة مستقلة. أما `:::pagebreak` فيرسل العناصر العائمة المعلّقة إلى الصفحة التي تليه ببساطة.

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

في الصفحة الختامية للفصل، وللمستند، لا يلي الأشكالَ والجداول بعرض الصفحة المنضّدة تحت آخر شريط نص شيءٌ، فترتفع لتقع على بُعد فجوة عنصر عائم واحدة تحته، متراصّة بترتيبها، بدل أن تترك بياضًا بين النص وشكل في أسفل الصفحة. ويسري ذلك على العنصر العائم ذي `position: 'bottom'` أيضًا. لإبقائها في أسفل الصفحة، كما في كل صفحة أخرى، اضبط `layout.hugClosingFloats: false` (انظر [الإعدادات › التخطيط](/ar/docs/configuration#التخطيط)). ولا تحرّكها أبدًا الصفحات التي فيها عمود جانبي.

ترسم الموارد المُخرِجات الثلاثة كلها: معاينة Canvas، وعارض HTML، ومخرجات PDF. وفي مُخرِج HTML تقيم بيانات الصور خارج المستند، فيوفّرها المضيف عبر خيار المُحلِّل `resourceImageUrl(fileId)`؛ وحين يغيب المُحلِّل (أو لا يعيد شيئًا لملف ما)، يُعرض المورد مربعًا محايدًا بديلًا كي يبقى التخطيط ثابتًا.

#### أين يمكن أن يستقر العنصر العائم

تُحسب قاعدة «أبدًا قبل إحالته» من السطر الذي يحيل إلى العنصر العائم: ينتظر العنصر العائم حتى يُنضَّد ذلك السطر، ويأخذ أول موضع شاغر بعده بترتيب القراءة، ورأس الصفحة التي يُنضَّد فيها السطر يقع قبله. والاستثناء هو العنصر العائم الجانبي (`span: 'side'`، في العمود الجانبي المخصص للعناصر العائمة في تخطيط العمود ونصف): يتراصّ في العمود الجانبي بجانب النص الذي يحيل إليه، وقد يقع أعلى في الصفحة من سطر الإحالة. لشكل يُحال إليه في الصفحة 5:

| الموضع | في الصفحة 5 | وإلا |
| --- | --- | --- |
| `top`، `span: 'page'` | أبدًا: الشريط الذي في رأس الصفحة يقع فوق سطر الإحالة. | الشريط العلوي في الصفحة 6. |
| `top`، `span: 'column'` | رأس عمود لاحق لا يزال فارغًا؛ فإذا أُحيل إليه في الأول من عمودين، أمكنه أن يفتتح الثاني. | رأس عمود في الصفحة 6. |
| `auto` أو `bottom`، `span: 'page'` | الشريط السفلي في الصفحة 5، حين يبقى في كل عمود متسع له. | شريط في الصفحة 6. |
| `auto` أو `bottom`، `span: 'column'` | أسفل عمود الإحالة؛ ثم أسفل (كلاهما) أو رأس (`auto` فقط) عمود فارغ لاحق. | الصفحة 6. |

- تتبع صفحة افتتاح الفصل القواعد نفسها: العنصر العائم بعرض الصفحة من نوع `auto` أو `bottom` الذي يُحال إليه في الفقرة الأولى من الافتتاح يمكنه أن يأخذ الشريط السفلي لتلك الصفحة، تحت نصها؛ أما عنصر `top` فيفتتح الصفحة التالية. ولكي تكون الصورة في الصفحة التي تحيل إليها، استعمل `auto` أو `bottom`، أو ارسمها عنصر صورة في تصميم الافتتاح.
- عنصران عائمان بعرض عمود يُحال إليهما في الفقرة نفسها يأخذان الموضعين التاليين: عادةً يأخذ الأول أسفل عمود الإحالة، والثاني رأس العمود الفارغ التالي، فيتجاوران في الصفحة.
- في التخطيط ذي العمود الواحد يكون العنصر العائم بعرض الصفحة عنصرًا عائمًا بعرض عمود، وتسري القواعد نفسها: عنصر `top` يُحال إليه في صفحة يستقر في رأس الصفحة التالية.
- الفقرة التي تمتد من صفحة إلى التالية تُحسب كذلك من سطر الإحالة فيها. حين تبدأ الفقرة في أسفل الصفحة 5 وتقع الإحالة في الصفحة 6، أو تنتقل الفقرة كلها إلى الصفحة 6 لأن ما يتسع من أسطرها في أسفل الصفحة 5 لا يكفي، تكون الإحالة في الصفحة 6: عنصر `top` يفتتح الصفحة 7، وعنصر `auto` يأخذ أسفل الصفحة 6 حين يتسع له. ويسري الأمر نفسه بين أعمدة الصفحة الواحدة، وعلى الإطار المقسوم على عدة صفحات: الشكل الذي يحيل إليه جزؤه الثاني ينتظر ذلك الجزء.
- **تغيّر في postext 1.5.** حتى postext 1.4 كان العنصر العائم يُدرج في قائمة الانتظار حين يصل التخطيط إلى الفقرة التي تحيل إليه، فكانت الصفحة التي تمتد إليها هذه الفقرة (أو تنتقل إليها) قد تُفتتح بالعنصر العائم، فوق السطر الذي يحمل الإحالة. أما الآن فيستقر هذا الشكل بعد صفحة، أو في أسفل الصفحة حين يطلب `auto`؛ وقد يترتب على ذلك تغيّر في عدد الصفحات.

## ما لا يدعمه Postext

لا يتعرّف Postext ميزات CommonMark التالية. فهي إما تُعامل نصًا عاديًا (فتظهر حرفيًا في المخرجات) وإما تُحذف بصمت:

- **العناوين بنمط Setext**، أي صيغة التسطير `===` / `---`. استعمل عناوين ATX (`#`).
- **كتل الشيفرة المسوّرة أو المُزاحة**، أي أسوار ` ``` ` أو `~~~` والإزاحة بأربع مسافات. تُقرأ الأسطر داخلها Markdown عاديًا، ولا تُحفظ قائمةً برمجية: الأسطر التي ليس بينها سطر فارغ تندمج في فقرة واحدة وتفقد مسافاتها البادئة، والسطر الذي يبدأ بـ`#` ومسافة يصير عنوانًا (ويبقى `#!/usr/bin/env` نصًا)، والسطر الذي يبدأ بـ`-` أو `1.` ومسافة يصير بند قائمة، وكل زوج من علامتي `$` يصير صيغة رياضية، وتُطبع أسطر السور نصًا: سور ` ``` ` علامةَ backtick واحدة، يتبع السورَ الافتتاحي سلسلةُ المعلومات (`` `bash``)، وسور `~~~` علامةَ `~` صغيرة واحدة تُنضّد منخفضة. لتنضيد قائمة برمجية، اكتب كل سطر فقرةً مستقلة (مع سطر فارغ بين الأسطر) داخل كتلة `:::paragraphs` يضبط نمط فقرتها `fontFamily` بخط أحادي المسافة، وأحط كل سطر بعلامتي backtick، فتحفظان `#` و`$` و`*` وسائر الرموز كما كُتبت. تُحذف المسافات العادية في بداية السطر، وتتقلص سلسلة منها داخل السطر إلى مسافة واحدة، داخل علامتي backtick أيضًا، فأزِح وحاذِ بمسافات غير فاصلة (U+00A0) وضعها داخل علامتي backtick: فالمسافة التي تسبق علامة backtick الافتتاحية تُحذف هي الأخرى. والشيفرة داخل السطر يُتعرَّف عليها، لكن ليس لها خط شيفرة: انظر [التنسيق داخل السطر](#التنسيق-المضمّن).
- **تمرير HTML**، فوسوم `<tags>` الخام لا تُفسَّر. ولا تُدعم الوسوم بأسلوب MDX أيضًا؛ فمصدر Postext هو Markdown خالص.
- **الخطوط الأفقية**، أي `---` و`***` و`___`.
- **الجداول**، فجداول الخطوط العمودية لا تُحلَّل. تُنمذج الجداول موارد مهيكلة في `PostextContent.resources`.
- **الروابط بأسلوب المراجع**، أي `[text][id]` مع كتلة تعريف.
- **الروابط التلقائية**، أي `<https://example.com>`.
- **الشطب**، أي `~~text~~`. أداة رسم الشطب محجوزة حاليًا لبنود المهام المكتملة.
- **ملاحظات الهامش**، فهي غير منفّذة، و`PostextContent.notes`، الذي تقبله الأنواع، يتجاهله المحرّك. أما الحواشي السفلية وتعليقات نهاية الفصل فتُكتب بـ`[^id]` (انظر [الحواشي السفلية](#الحواشي-السفلية))؛ وحتى postext 1.5 كان لا بد من تنضيدها نصًا.

ستقصر هذه القائمة مع الوقت. وإلى ذلك الحين، ينبغي افتراض أن كل ما لم يُذكر صراحةً في قسم الميزات المدعومة أعلاه نص حرفي.

وبعيدًا عن الصياغة، تُنضَّد العربية وسائر الكتابات التي تُكتب من اليمين إلى اليسار من اليمين إلى اليسار، مع الخوارزمية ثنائية الاتجاه والتجليد من اليمين (انظر [الإخراج العربي](/ar/docs/arabic-layout)). وتُنضَّد الصينية أفقيًا عبر الصفحة وعموديًا نزولًا فيها، مع قواعد كسر الأسطر وعروض علامات الترقيم وضبط الأسطر بين المحارف والعلامات والروبي (ruby) والواريتشو (warichu) التي تقتضيها منطقتها (انظر [الإخراج الصيني](/ar/docs/chinese-layout))؛ وتمر اليابانية والكورية عبر المُنضِّد نفسه بقواعد الصين القارية. وتأتي أنماط تقسيم الكلمات بالواصلة لثماني لغات، والتسميات المدمجة لتلك الثماني وللصينية والعربية. انظر [اللغات والكتابات](/ar/docs/configuration#اللغات-وأنظمة-الكتابة).

## أعراف التأليف

بضعة أعراف تصنع الفرق بين مستند يُحلَّل بسلاسة ومستند يفاجئك:

- **اترك سطرًا فارغًا بين الكتل.** فقرتان يفصلهما سطر فارغ فقرتان. وفقرتان في سطرين متتاليين تصيران فقرة واحدة، إذ يندمج كل سطر في الفقرة السابقة.
- **الأسطر الفارغة الزائدة لا تضيف مسافة.** ثلاثة أسطر فارغة تفصل بين كتلتين تمامًا كسطر واحد. وحين تريد مسافة أكبر بينهما، اكتب سطر [`:::space`](#space).
- **أدرج القوائم المتداخلة بمسافتين بالضبط لكل مستوى.** المسافة الواحدة تُحلَّل بندًا من المستوى 1. وثلاث مسافات أو أربع تُقرَّب إلى الأدنى إلى المستوى 2 (يستعمل المحرّك `floor(leading / 2) + 1`، محصورًا في العمق 5). ولا تُتعرَّف الإزاحة بعلامة الجدولة (tab)، فحوّل علامات الجدولة إلى مسافات.
- **لا تُزِح بند القائمة الأول.** تبدأ بنود المستوى 1 عند العمود 0. والمسافة البيضاء البادئة قبل النقطة ترفع العمق ضمنيًا.
- **يجب أن تكون علامات المهام بين قوسين مربعين مع مسافة واحدة.** `[ ]`، `[x]`، `[X]`، دون أي تنويع. `[*]` أو `[-]` ليستا علامتي مهام، وتظهران نصًا حرفيًا.
- **الاقتباسات الكتلية داخل القوائم غير مدعومة.** ابدأ الاقتباس الكتلي عند العمود 0، خارج القائمة.
- **الصور والجداول مكانها `resources`.** تُزال الصيغة داخل السطر `![alt](src)` تحديدًا لأن الصور داخل السطر تُفسد الوضع المراعي للأعمدة. عرّف كل صورة موردًا وأحِل إليها بمعرّفها، فيقرر المحرّك عندئذ هل تطفو، أم تقطع العمود، أم تنتقل إلى أعلى الصفحة التالية.
- **هرّب علامات الدولار بـ`\$` حين لا تقصد رياضيات.** يفسّر Postext الصيغة `$…$` بوصفها LaTeX داخل السطر، فعلامة `$` الخام في النص تبدأ صيغة رياضية. الأسعار ومحثّات الصدفة (shell prompts) وكل ما فيه علامة دولار مجردة ينبغي أن يُكتب `\$`.
- **اكتب الترميز بمحارف ASCII، في النص الصيني أيضًا.** تُعطي طريقة الإدخال الصينية أو اليابانية الصيغ كاملة العرض: `：：：` للسور، و`＃` للعنوان، و`［＾1］` لعلامة الحاشية، و`｛…｝` للسمات، و`＊＊` للعريض. فتُطبع نصًا، ويبلّغ البناء عن السطر بتحذير `fullwidthMarkup` يسمّي صيغة ASCII الواجب كتابتها. ويمكن أن تكون قيم السمات بأي كتابة وأن تُحاط بـ`“…”` أو `「…」`؛ أما المفاتيح فتبقى ASCII.

## مثال تطبيقي

مستند قصير يستعمل كل بنية مدعومة:

```md
---
title: The Typesetter's Craft
author: Anon
---

# Opening

A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.

## What makes text readable

Three properties matter most:

1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
   a. Tighter at short measures.
   b. Looser at long measures.
3. Contrast between body and headings.

Common failure modes include:

- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.

> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst

### Review checklist

- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread

### A note on formulas

Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:

$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$
```

ويُنتج المستند نفسه، حين يمر عبر محرّك الإخراج، كائن `VDTDocument` مهيكلًا تحمل صفحاته كل كتلة من هذه الكتل مُدخلاتٍ ذات أنواع؛ انظر صفحة [البنية](/ar/docs/architecture) لمعرفة كيف تتحول الكتل إلى هندسة.