# الإعدادات: الحواشي والإحالات

> الحواشي السفلية وترقيم الأسطر والإحالات المرجعية والاستشهادات، وجدول المحتويات والفهرس الأبجدي

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

## باختصار

تتناول هذه الصفحة إعدادات أجزاء الكتاب التي تحيل إلى موضع آخر. تقع الحواشي أسفل الصفحة، وتقع أرقام الأسطر في الهامش. تشير الإحالات المرجعية إلى شكل أو قسم أو صفحة، وتشير الاستشهادات إلى المؤلفات التي تذكرها. يسرد جدول المحتويات الفصول، ويسرد الفهرس الأبجدي في آخر الكتاب المصطلحات مع صفحاتها. ويشرح كل قسم مظهر هذه الأجزاء وطريقة ترقيمها.

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

تحدد الخاصية `footnotes` أين تذهب الحواشي المستشهد بها عبر `[^id]`، وكيف تُرقَّم وكيف تبدو. الترميز موصوف في [صيغة المستند](https://postext.dev/ar/docs/document-format.md#الحواشي-السفلية).

```ts
interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Foot of the citing column, after the chapter, or beside the text of a spread.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Start again at each chapter, run on, or start again on each page / column / spread.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // رموز الإحالة التي يكتبها numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Raised, on the baseline, beside the word, or right of a vertical line.
  markerSize?: Dimension;     // Inline, side or right marker size; em is the text around it.
  numberGap?: 'en' | 'em';    // Space after the note's own number.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes at the column foot, or under the text.
  fontSize?: Dimension;       // Note size; em is the body size.
  lineHeight?: Dimension;     // Note leading; em is the note size.
  color?: ColorValue;         // Note colour; the body colour when unset.
  textAlign?: TextAlign;      // The body alignment when unset.
  hangingIndent?: Dimension;  // Indent of a note's turnover lines.
  spaceBetween?: Dimension;   // Space between two notes.
  spaceAbove?: Dimension;     // Space between the text and the rule; em is the body size.
  spaceBelowRule?: Dimension; // Space between the rule and the first note.
  separator?: {
    enabled?: boolean;        // Draw the rule.
    width?: number;           // Rule length, a fraction of the column width.
    lineWidth?: Dimension;    // Rule thickness.
    color?: ColorValue;       // The note colour when unset.
  };
}
```

| الخاصية | النوع | القيمة الافتراضية | الوصف |
| --- | --- | --- | --- |
| `placement` | `'column' \| 'chapterEnd' \| 'spread'` | `'column'` (الكتب اليابانية العمودية: `'chapterEnd'`) | `'column'` تضع كل حاشية في أسفل العمود الذي يحوي السطر المستشهِد بها، تحت خط فاصل قصير؛ وفي تخطيط من عمود واحد يكون ذلك أسفل الصفحة. و`'chapterEnd'` تضع كل حواشي الفصل بعد آخر كتلة فيه، بترتيب الاستشهاد. و`'spread'` (傍注، للنص العمودي وحده) تضع الحواشي المستشهد بها في صفحتَي الصفحتين المتقابلتين في آخر صفحتهما الفردية، وهي الصفحة اليسرى في الكتاب المجلّد من اليمين، تحت الخط الفاصل: فالحواشي المستشهد بها في الصفحة الزوجية تنتظرها، والحاشية التي كانت ستترك للصفحة الفردية أقل من سطر نص واحد تبقى في أسفل الصفحة الزوجية مع ما بعدها، والفصل الذي ينتهي في صفحة زوجية يُبقي حواشيه المنتظرة فيها. وفي النص الأفقي تعود إلى `'column'` مع التحذير `unknownConfigValue`. منذ postext 1.16. |
| `numbering` | `'chapter' \| 'document' \| 'page' \| 'column' \| 'spread'` | `'chapter'` (الكتب اليابانية الأفقية: `'page'`؛ ومع `placement: 'spread'`: `'spread'`؛ ومع `numberFormat: 'symbols'` في ذيل العمود: `'page'`) | `'chapter'` تبدأ من 1 من جديد تحت كل عنوان من المستوى 1 وفي بداية كل مستند. و`'document'` تستمر عبر المستند، وفي الكتاب الذي يُخرَج فصلًا فصلًا تستمر من فصل إلى الذي يليه (تحمل `continuationAfter` الرقم الأخير في `continuation.footnoteNumber`). و`'page'` تبدأ من 1 من جديد في كل صفحة، و`'column'` في كل عمود، فتعدّ الحواشي حيث يضعها الإخراج (أعمدة الصفحة بترتيب القراءة): وهي الحواشي المعتادة أسفل الصفحة في الكتاب الصيني، 页下注. يُخرَج المستند، ثم يُرقَّم بحسب المواضع التي وقعت فيها حواشيه، ثم يُعاد إخراجه حتى تثبت الأرقام (ثلاث عمليات بناء إضافية على الأكثر). كلتاهما تنطبقان على الحواشي في أسفل العمود: مع `placement: 'chapterEnd'` تُرقَّم الحواشي بحسب الفصل. و`'spread'` تبدأ من جديد في كل صفحتين متقابلتين (الصفحتان 2–3، و4–5…)، بترتيب الاستشهاد، مع `placement: 'spread'`. |
| `numberFormat` | `string` | `'decimal'` | طريقة كتابة الأرقام، بأي صيغة كتابة تقبلها إعدادات الترقيم: `'decimal'`، `'lower-roman'`، `'lower-alpha'`، `'circled-decimal'` (أو `'①'`)، `'cjk-decimal'`، `'一'`… وتستخدمها العلامة والرقم الذي يفتتح الحاشية كلاهما. تكتب `circled-decimal` الأرقام التي تتجاوز 50 بالأرقام العشرية. والاسم غير المعروف يُرقِّم بالأرقام العشرية، مع تحذير `unknownNumberFormat`. وتُعلِّم `'symbols'` (أو `'*'`) الحواشي برموز الإحالة، رموز `symbols` بالترتيب: * † ‡ § ‖ ¶، ثم مضاعفةً (** †† ‡‡…) ثم مثلَّثة؛ وعندئذ يُعاد عدّ الحواشي في كل صفحة ما لم يُضبط `numbering`. منذ postext 1.19. |
| `symbols` | `string[]` | `['*', '†', '‡', '§', '‖', '¶']` | التسلسل الذي يكتبه `numberFormat: 'symbols'`، يُضاعَف ثم يُثلَّث متى نفد. تحمل الملفات اللاتينية في Google Fonts وFontsource الرموز * † § ¶ (الخنجر في `latin-ext`) دون ‡ و‖، فيرسمهما ملف PDF بمحرف `.notdef` في الخط مع تحذير `missingGlyph`: مع خط كهذا احذفهما (`['*', '†', '§', '¶']`) أو صُفَّ الحواشي بخط يحتويهما. تُهمَل السلاسل الفارغة، وتُبقي القائمة الفارغة التسلسل الافتراضي. منذ postext 1.19. |
| `markerPosition` | `'auto' \| 'superscript' \| 'inline' \| 'side' \| 'right'` | `'auto'` | `'superscript'` ترفع العلامة في النص والرقمَ الذي يفتتح الحاشية، بحجم مصغَّر. و`'inline'` تضعهما على خط الأساس: العلامة بحجم `markerSize`، ورقم الحاشية بحجم الحاشية؛ وفي النص الرأسي تقف العلامة الدائرية ضمن السطر منتصبةً في خلية خاصة بها. و`'right'` تضع علامة مصغّرة ملاصقة للجانب الأيمن من السطر العمودي، كما تنضّد الكتب اليابانية العمودية （1）؛ وفي النص الأفقي تكون مرفوعة. و`'side'` (合印) تضع علامة صغيرة بجانب الكلمة المعلَّمة، على جانب الروبي فيها، تنتهي حيث ينتهي آخر حرف في الكلمة؛ ولا تأخذ حيّزًا في السطر، الذي ينكسر ويُضبط كأنها غير موجودة، والفجوة بين الأسطر الأضيق من أن تتسع لها يُبلَّغ عنها بالتحذير `rubyExceedsLeading`. و`'auto'` تعني ضمن السطر مع `circled-decimal`، و`'right'` في الكتاب الياباني العمودي، ومرفوعة في غير ذلك. وفي الحالتين تبقى العلامة مع الحرف الذي قبلها ولا تفتتح سطرًا أبدًا. |
| `markerSize` | `Dimension` | `1em`؛ و`0.6em` مع `'side'`، و`0.7em` مع `'right'` | حجم العلامة ضمن السطر أو الجانبية أو اليمنى؛ و`em` هو حجم النص المحيط بها (`0.75em` تصغير شائع). لا أثر له في العلامة المرفوعة. |
| `numberGap` | `'en' \| 'em'` | `'en'` (الحواشي اليابانية بعد الفصل: `'em'`) | المسافة بعد الرقم الذي يفتتح الحاشية: مسافة en، أو em كامل بحجم الحاشية (مسافة إيديوغرافية حين يحوي الرقم أو الحاشية نص CJK)، لا تتسع ولا تنكسر أبدًا. منذ postext 1.16. |
| `markerTemplate` | `string` | `'{n}'` (الكتب اليابانية العمودية: `'（{n}）'`) | طريقة كتابة رقم الحاشية، حيث يمثّله `{n}` بتنسيق الترقيم وبأرقام المستند: `'({n})'` تعطي العلامات المحاطة بأقواس المعهودة في الكتب العربية، «(١)». وتكتب بها العلامةَ في النص والرقمَ الذي يفتتح الحاشية على السواء. والقالب الذي يخلو من `{n}` يُقرأ على أنه القيمة الافتراضية. |
| `noteNumberPosition` | `'auto' \| 'superscript' \| 'inline'` | `'auto'` | موضع الرقم الذي يفتتح الحاشية: مرفوعًا، أو على السطر بحجم الحاشية. `'auto'` تتبع `markerPosition`. الكتب العربية ترفع العلامة في النص وتضع رقم الحاشية نفسها على السطر. |
| `chapterEndAlign` | `'foot' \| 'text'` | `'foot'` | مع `placement: 'chapterEnd'`: `'foot'` تضع الحواشي التي تختم عمودًا في أسفله، وتبقى الأسطر المتبقية بين النص والحواشي، كما تقف الحواشي في أسفل العمود. و`'text'` تضعها مباشرةً تحت النص. |
| `fontSize` | `Dimension` | `0.8em` | حجم نص الحاشية. `em` و`rem` هما حجم المتن. تستخدم الحواشي عائلة خط المتن وأوزانه. |
| `lineHeight` | `Dimension` | `1.25em` | تباعد أسطر نص الحاشية؛ و`em` هو حجم الحاشية. الحواشي خارج شبكة خطوط الأساس: تتراكم صعودًا من أسفل العمود، ويبقى النص فوقها على الشبكة. |
| `color` | `ColorValue` | لون المتن | لون نص الحاشية. |
| `textAlign` | `TextAlign` | محاذاة المتن | محاذاة نص الحاشية. |
| `hangingIndent` | `Dimension` | `0` | إزاحة السطر الثاني وما بعده من الحاشية، كي تصطف بعد رقمها. |
| `spaceBetween` | `Dimension` | `0` | المسافة بين حاشيتين. |
| `spaceAbove` | `Dimension` | `0.5em` | المسافة بين آخر سطر من النص والخط الفاصل؛ و`em` هو حجم المتن. مع `'chapterEnd'` و`chapterEndAlign: 'text'`، يكون مجموع `spaceAbove` + `spaceBelowRule` هو المسافة بين النص وأول حاشية. |
| `spaceBelowRule` | `Dimension` | `0.4em` | المسافة بين الخط الفاصل وأول حاشية. |
| `separator.enabled` | `boolean` | `true` | يرسم الخط الفاصل فوق حواشي كل عمود. ومع `false` تبقى المسافات التي فوقها. |
| `separator.width` | `number` | `0.3` | طول الخط الفاصل كسرًا من عرض العمود (0–1)، بدءًا من الحافة اليسرى للعمود. |
| `separator.lineWidth` | `Dimension` | `0.5pt` | سُمك الخط الفاصل. |
| `separator.color` | `ColorValue` | لون الحاشية | لون الخط الفاصل. |

```ts
footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}
```

**الكتب اليابانية.** المستند الياباني (`locale: 'ja'`، منذ postext 1.16) يعطي الحقول التي يتركها دون ضبط قيم JLReq §4.2. فالكتاب العمودي يضع حواشيه بعد الفصل (`placement: 'chapterEnd'`، 後注)، مرقّمة بحسب الفصل، مع علامات `（{n}）` على يمين السطر (`markerPosition: 'right'`، والأرقام قائمة بحسب `cjk.uprightDigits`)؛ والأفقي يضعها في أسفل الصفحة، مرقّمة لكل صفحة، مع علامات مرفوعة. وكلاهما يرسم الخط الفاصل بطول ثلث عرض السطر (`separator.width: 1/3`)، والحواشي بعد الفصل تأخذ `numberGap: 'em'` ومسافة بادئة معلّقة بعرض 2 em. والقيمة الصريحة هي التي تُعتمد، وتُحفظ عند الحفظ (يقارن `stripFootnotesDefaults` بالقيم الافتراضية للمستند نفسه)؛ وتُحسم المستندات الصينية والعربية واللاتينية كما كانت. وتعيد `footnoteDocumentDefaults(locale, writingMode, placement?)` هذه القيم. واكتب العلامة قبل 。 التي تختم الجملة (`先生[^1]。`): فهي تبقى مع الحرف الذي قبلها، و。 لا تفتتح سطرًا أبدًا. انظر [الإخراج الياباني › الحواشي](https://postext.dev/ar/docs/japanese-layout.md#الحواشي).

كيف تُخرَج الحواشي في أسفل العمود:

- **الحاشية والاستشهاد يتشاركان العمود.** قبل أن يضع الإخراج سطرًا، يضيف ارتفاع الحواشي التي يستشهد بها ذلك السطر لأول مرة (والخط الفاصل، مع أول حاشية في العمود). والسطر الذي لا تتسع حواشيه تحته ينتقل إلى العمود التالي مع بقية فقرته، وفق قاعدتي الأسطر اليتيمة والأرامل. تتقلص مساحة النص في العمود بمقدار ارتفاع الحواشي، فلا تحسب موازنةُ الأعمدة والشريطُ الختامي للفصل إلا النص.
- **عدة حواشي** في عمود واحد تتراكم بترتيب الاستشهاد تحت خط فاصل واحد. والحاشية التي يُستشهد بها مرة أخرى لاحقًا تحتفظ برقمها ولا تُنضَّد ثانيةً.
- **العناصر العائمة السفلية.** الشكل الذي يشغل أسفل عمود بعد وضع حواشيه يوضع فوقها؛ والحواشي التي توضع بعد الشكل تأتي فوقه.
- **الإطارات.** الحاشية المستشهد بها داخل إطار (ضمن السطر أو عائم أو ثابت) تذهب إلى أسفل العمود الذي يستمر فيه النص بعد الإطار، وهو عادةً العمود نفسه. والإطار الذي يختم المستند يترك حواشيه في أسفل العمود الذي انتهى فيه النص.
- **الحدود.** لا تُقسَم الحاشية أبدًا: الحاشية الأطول من العمود تفيض منه. والعلامات في التعليقات وخلايا الجداول والعناوين لا تُقرأ (تُطبع كما كُتبت).
- **المُخرجات.** ترسم Canvas وHTML وPDF الحواشي والعلامات (رقمًا مرفوعًا) والخط الفاصل. في PDF ترتبط كل علامة بحاشيتها، وPDF الموسوم يجعل كل حاشية عنصر `Note` بمعرّف `/ID` فريد مُدرج في `/IDTree` من شجرة البنية (PDF/UA-1). الحواشي كتل `VDTBlock` عُيّنت فيها `footnoteNote`، في `page.floats`؛ والخطوط الفاصلة في `page.footnoteAreas`.
- **التحذيرات.** `undefinedFootnote` (علامة بلا تعريف: يُطبع الرقم فوق حاشية فارغة) و`unusedFootnote` (تعريف لا تستشهد به أي علامة: لا يُنضَّد).

دالتا الحل والتجريد مماثلتان لنظيراتهما في الأقسام الأخرى:

```ts
import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';

resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // unset fields take the Japanese vertical defaults
```

## ترقيم الأسطر

تطبع الخاصية `lineNumbers` في الهامش رقمَ كل سطر خامس (أو كل سطر رقمه من مضاعفات N) بجوار السطر، كما تفعل الطبعات المحققة ومختارات الشعر والنصوص القانونية والطبعات المدرسية. وهي تعدّ أبيات قصائد `:::verse`، أو كل أسطر النص. وهي معطّلة افتراضيًا. يُرسم كل رقم على خط قاعدة سطره، بحجم خاص به، ولا يحرّك أي سطر أبدًا: تُخرَج الصفحة تمامًا كما تُخرَج بلا أرقام. منذ postext 1.23.

```ts
interface LineNumbersConfig {
  enabled?: boolean;        // معطّلة افتراضيًا.
  count?: 'verse' | 'all';  // أبيات القصائد، أو كل أسطر النص.
  interval?: number;        // اطبع مضاعفات N.
  numberFirst?: boolean;    // اطبع أيضًا أول سطر بعد كل إعادة للعدّ.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // أين يبدأ العدّ من جديد.
  startAt?: number;         // رقم أول سطر بعد إعادة العدّ.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // الصفحات ذات العمودين أو أكثر.
  gap?: Dimension;          // من النص إلى الرقم؛ وem حجم الرقم.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // عائلة خط المتن إن لم تُحدَّد.
  fontSize?: Dimension;     // وem حجم المتن.
  fontWeight?: number;      // وزن المتن إن لم يُحدَّد.
  italic?: boolean;
  color?: ColorValue;       // لون المتن إن لم يُحدَّد.
  format?: string;          // decimal، lower-roman، arabic-indic، 一…
}
```

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `false` | يطبع أرقام الأسطر. المستند العمودي (`layout.writingMode: 'vertical-rl'`) لا يأخذ أي رقم، ويُبلَّغ عن `true` فيه بالتحذير `lineNumbersUnsupported`. |
| `count` | `'verse' \| 'all'` | `'verse'` | `'verse'` يعدّ أبيات قصائد `:::verse`، كل بيت مرة واحدة: ما ينتقل إلى السطر التالي من بيت أطول من العرض لا يأخذ رقمًا، والمسافة بين المقاطع لا تُعدّ. والقصيدة المنضّدة بالتخطيط العربي الكلاسيكي تعدّ سطرًا واحدًا لكل بيت؛ والسطر الثاني من البيت المدرَّج لا يُعدّ. و`'all'` يعدّ كل أسطر فقرات المتن وعناصر القوائم والاقتباسات والأبيات، بترتيب القراءة: صفحةً صفحة، وعمودًا عمودًا، من الأعلى إلى الأسفل. |
| `interval` | `number` | `5` | يطبع رقم كل سطر رقمه من مضاعفات هذا العدد (5، 10، 15…). والقصيدة التي أول أبياتها 37 تطبع 40، 45… ويمكن لسطر فتح القصيدة أن يحدّد فاصلًا خاصًا بها (`interval=N`). |
| `numberFirst` | `boolean` | `false` | يطبع أيضًا رقم أول سطر يُعدّ بعد كل إعادة للعدّ. |
| `restart` | `'document' \| 'chapter' \| 'section' \| 'page' \| 'poem'` | `'poem'` مع `count: 'verse'`، و`'page'` مع `count: 'all'` | أين يبدأ العدّ من جديد: أبدًا (`'document'`، فيستمر عبر فصول الكتاب)، أو عند كل عنوان من المستوى 1 (`'chapter'`)، أو عند كل عنوان من المستوى 1 أو 2 (`'section'`)، أو في كل صفحة (`'page'`)، أو عند كل قصيدة `:::verse` (`'poem'`). ويعيد `lineStart=N` في قصيدة و`lines=N` في الموجّه `:::numbering` العدَّ في أي موضع، أيًّا كان الوضع. |
| `startAt` | `number` | `1` | رقم أول سطر بعد إعادة العدّ. |
| `position` | `'outer' \| 'inner' \| 'left' \| 'right' \| 'start' \| 'end' \| 'side'` | `'outer'` | الجهة التي تقف فيها الأرقام. `'outer'` هي الجهة البعيدة عن الكعب: يمين الصفحة الفردية ويسار الزوجية، وبالعكس في الكتاب المجلَّد من اليمين. و`'inner'` جهة الكعب. و`'left'` و`'right'` ثابتتان في كل الصفحات. و`'start'` و`'end'` تتبعان اتجاه المستند: `'start'` هي اليمين في كتاب من اليمين إلى اليسار. و`'side'` تضعها في العمود الجانبي لتخطيط `'oneAndHalf'` مع `layout.sideColumnRole: 'floats'`، ملاصقةً لحافة العمود الجانبي المجاورة للنص (ولا يُستعمل `gap`)؛ وفي صفحة بلا عمود جانبي تعود إلى `'outer'`. |
| `multiColumn` | `'each' \| 'gutter' \| 'outer-edges'` | `'outer-edges'` | الصفحات التي فيها عمودان من النص أو أكثر جنبًا إلى جنب. `'outer-edges'` تضع أرقام العمود الأول على يساره وأرقام العمود الأخير على يمينه، وتتبع الأعمدة بينهما `'each'`. و`'gutter'` تضعها في الفواصل بين الأعمدة: أرقام العمود الأول على يمينه، وأرقام غيره على يسارها. و`'each'` تضع أرقام كل عمود في جهة `position`. |
| `gap` | `Dimension` | `1em` | المسافة من حافة العمود إلى الرقم؛ و`em` حجم الرقم نفسه. |
| `align` | `'auto' \| 'left' \| 'right'` | `'auto'` | `'auto'` تحاذي كل رقم نحو النص: إلى اليمين في هامش أيسر، وإلى اليسار في هامش أيمن. و`'left'` و`'right'` تحاذيان الأرقام داخل عرض أعرض رقم في الصفحة. |
| `fontFamily` | `string` | عائلة خط المتن | خط الأرقام. يُحمَّل ويُضمَّن كأي عائلة أخرى. |
| `fontSize` | `Dimension` | `0.8em` | حجم الأرقام؛ و`em` حجم المتن. |
| `fontWeight` | `number` | وزن المتن | وزن الأرقام. |
| `italic` | `boolean` | `false` | ينضّد الأرقام بخط مائل. |
| `color` | `ColorValue` | لون المتن | لون الأرقام. واللون المرتبط باللوحة يتبع لوحات الأجزاء والأقسام. |
| `format` | `string` | عشري | كيف تُكتب الأرقام، بأي من [صيغ كتابة أنماط الترقيم](https://postext.dev/ar/docs/configuration-page-layout.md#صيغ-كتابة-أنماط-الترقيم) (`'lower-roman'`، `'arabic-indic'`، `'一'`…). وتُكتب الأرقام العشرية بأرقام المستند (`numerals`). والاسم غير المعروف يرقّم بالعشري، مع التحذير `unknownNumberFormat`. |

```ts
lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // عدّ واحد للكتاب كله
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}
```

ما يُعدّ وما لا يُعدّ:

- **لا يُعدّ أبدًا**: العناوين، والتعليقات، والجداول والصور، والصيغ المنفصلة، ونصوص التصميم (صفحات الافتتاح والترويسات)، والحواشي السفلية وحواشي آخر الفصل، وجدول المحتويات، ومداخل الفهرس وقائمة المراجع، والصفحات الفارغة.
- **الإطارات والنثر.** نص الإطار لا يُعدّ، ومع `count: 'verse'` لا يُعدّ النثر أيضًا، إلا إذا قال نمط الفقرة الذي يُنضَّد به `lineNumbers: true`؛ والنمط الذي فيه `lineNumbers: false` لا يُعدّ أبدًا (انظر [أنماط الفقرات](https://postext.dev/ar/docs/configuration-styles.md#أنماط-الفقرات)).
- **قصيدة واحدة.** يقبل سطر فتح القصيدة `numbered=false` (لا تُعدّ أبياتها)، و`lineStart=N` (أول أبياتها رقمه N، ومنه يبدأ العدّ من جديد)، و`interval=N`. و`:::numbering{lines=N}` يعطي السطرَ المعدود التالي الرقمَ N، أينما كان. انظر [صيغة المستند › `:::verse`](https://postext.dev/ar/docs/document-format.md#verse) و[`:::numbering`](https://postext.dev/ar/docs/document-format.md#numbering).

في كتاب يُخرَج فصلًا فصلًا، ينقل `restart: 'document'` العدّ من فصل إلى الذي يليه عبر `continuation.lineNumber`. ويعدّ `continuationAfter` الأبيات من النص؛ أما مع `count: 'all'` فيتوقف العدّ على الإخراج، فيمرّر التطبيق المضيف `lastLineNumber` من مستند الفصل السابق، كما يفعل Sandbox.

مع `position: 'side'` تتقاسم الأرقام العمود الجانبي مع الإطارات والتعليقات والأشكال الجانبية. والرقم الذي يتراكب مع أحدها يُرسم مع ذلك، ولا يتحرك أيٌّ منهما، ويصدر الإخراج تحذير محتوى `lineNumberOverlap` يشير إلى السطر المرقَّم.

**المُخرجات.** ترسم Canvas وPDF وعارض HTML وEPUB ذو التخطيط الثابت الأرقام. وفي PDF الموسوم تكون عناصر زخرفية (artifacts) في الإخراج، ويحمل كل منها `/ActualText` فارغًا، فينتقل النص المنسوخ أو المستخرج من سطر إلى سطر بدونها. ويخفيها مُخرَج HTML عن التقنيات المساعدة (`aria-hidden`) وعن التحديد وعن النص المنسوخ. أما EPUB المتدفق، الذي ينضّد نظام القراءة أسطره، فيحتفظ بأرقام الأبيات وحدها: عنصر `span` من الصنف `pt-line-number` (و`aria-hidden` هو أيضًا) في هامش البداية من المقطع، بجوار كل بيت يحمل رقمًا في النسخة المطبوعة. وفي VDT تكون الأرقام خانة تصميم في كل صفحة (`page.lineNumbers`، وكتل نصها معلَّمة بـ `artifact`) وقائمة علامات (`page.lineNumberMarks`: `number` و`label` و`columnIndex` و`blockId` و`lineIndex`)؛ ويسجّل المستند `lastLineNumber`.

**غير مدعوم**: أرقام الأسطر في النص العمودي، والإحالة المرجعية التي تطبع رقم سطر، والحواشي المربوطة بأرقام الأسطر، وأرقام أسطر خلايا الجداول والتعليقات وقوائم الشيفرة.

في Sandbox هذه الإعدادات هي قسم **ترقيم الأسطر** في لوحة التصميم. ودالتا الحل والتجريد مماثلتان لنظيراتهما في الأقسام الأخرى؛ والخط والوزن واللون تأتي من المتن:

```ts
import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';

resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // الخط والوزن واللون غير المحدَّدة تتبع المتن
```

## الإحالات المرجعية

تحدد الخاصية `crossRefs` الكلمات التي تطبعها [الإحالة المرجعية](https://postext.dev/ar/docs/document-format.md#الإحالات-والمراسي) حول رقم أو صفحة، والنمطَ الذي تأخذه `:ref` حين لا تحدد نمطًا. يحمل كل قالب `{n}` حيث يوضع الرقم؛ والقالب الذي يخلو منه يأتي الرقم بعده مسبوقًا بمسافة غير قابلة للكسر (`"§"` يطبع *§ 3.2*). والقالب غير المعيَّن يتبع لغة المستند: *chapter / section / p.* بالإنجليزية، و*capítulo / sección / pág.* بالإسبانية، و`第{n}章` / `第{n}节` / `第{n}页` بالصينية، وهكذا للفرنسية والألمانية والإيطالية والبرتغالية والكتالونية والهولندية.

```ts
interface CrossRefsConfig {
  chapter?: string;  // Words around a level-1 heading's number: "chapter {n}".
  section?: string;  // Around any other heading's number: "section {n}".
  page?: string;     // Around a page number: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // A :ref without style=.
}
```

| الخاصية | النوع | القيمة الافتراضية | الوصف |
| --- | --- | --- | --- |
| `chapter` | `string` | بحسب اللغة | إحالة إلى عنوان من المستوى 1: `"chapter {n}"`. ورقم العنوان الذي يتضمن قالبُه الكلمةَ أصلًا (`Chapter {1}`، `第{1:一}章`) يُطبع كما هو. |
| `section` | `string` | بحسب اللغة | إحالة إلى عنوان من المستوى 2 إلى 6: `"section {n}"`، `"§ {n}"`. |
| `page` | `string` | بحسب اللغة | إحالة إلى صفحة (`style=page`): `"p. {n}"`، `"page {n}"`. |
| `defaultStyle` | `'default' \| 'number' \| 'title' \| 'page'` | `'default'` | ما تطبعه `:ref` إلى عنوان أو مرساة دون `style=`. `'default'`: العنوان المرقّم بكلمته ورقمه، وغير المرقّم بنص عنوانه، والمرساة بنصها. والإحالة التي تعيّن `style` تحتفظ به، ولا تتأثر الإحالات إلى الأشكال والجداول. |

تأخذ الإحالات لون كل إحالة ووزن خطها وميلها (`bodyText.referenceColor`، `referenceBold`، `referenceItalic`).

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

تختار الخاصية `citations` نمط الاستشهاد وطريقة ظهور الاستشهادات وقائمة المراجع. الترميز موصوف في [الاستشهادات والمراجع](https://postext.dev/ar/docs/document-format.md#الاستشهادات-وقائمة-المراجع)؛ ويطبّق النمطَ الحزمةُ `postext-citeproc`.

```ts
interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… or 'custom'
  customStyle?: string;    // a whole CSL style (.csl XML), used with style: 'custom'
  locale?: string;         // CSL locale; the document language when unset
  link?: boolean;          // citations link to their entries
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // unset: the document language's word; '' or ' ': none
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}
```

| الخاصية | النوع | القيمة الافتراضية | الوصف |
| --- | --- | --- | --- |
| `style` | `string` | `'apa'` | معرّف نمط مضمَّن (انظر [الأنماط](https://postext.dev/ar/docs/document-format.md#الأنماط)) أو `'custom'`. النمط هو الذي يقرر ما تقوله الاستشهادات والمُدخلات: الأسماء، والتواريخ، والترتيب، وعلامات الترقيم، وهل الاستشهادات حواشٍ. |
| `customStyle` | `string` | — | نمط CSL كامل، أي محتوى XML لملف `.csl`، يُستخدم حين تكون `style` هي `'custom'`. يحمّله Sandbox من ملف. |
| `locale` | `string` | لغة المستند | لغة CSL المحلية التي يكتب بها النمط كلماته (`en-US`، `es-ES`، `zh-CN`، `zh-TW`، `ja-JP`…). والمستند الياباني يُقرأ على أنه `ja-JP`: تصل الاستشهادات السردية بين مؤلفَين بـ と وتختصر الأكثر بـ ほか. |
| `link` | `boolean` | `true` | يرتبط الاستشهاد بمُدخله في قائمة المراجع (رابط في PDF، ومرساة في HTML، ونقرة في Sandbox). |
| `marker` | `'style' \| 'brackets' \| 'parentheses' \| 'superscript' \| 'corner'` | `'style'` | كيف يعلّم النمط المرقَّم الاستشهاد: كما يكتبه النمط، أو `[1]`، أو `(1)`، أو رقمًا مرفوعًا، أو `〔1〕` (منتصبًا في النص الرأسي). ويلي الرقمَ محدِّدُ الموضع (locator). |
| `collapseRanges` | `boolean` | `true` | الأرقام المتتالية تُكتب نطاقًا: `1–3` في علامة واحدة خاصة بها، و`[2]–[4]` في نمط IEEE. و`false` تبقيها منفصلة. |
| `notes` | `'footnote' \| 'warichu'` | `'footnote'` | أين يضع نمطُ الحواشي استشهاداته: في حواشٍ سفلية (توضع وتُرقَّم كما تحدد `footnotes`)، أو في تعليقات من صفين داخل السطر (夹注). |
| `numbering` | `'book' \| 'chapter'` | `'book'` | الاستشهادات عبر الكتاب كله، أو كل فصل وحده (كل مستند، وكل عنوان من المستوى 1 بعد استشهاد): يرقّم النمط الرقمي كل فصل من 1، ويأخذ العمل المستشهد به في فصلين رقم كل فصل؛ ويكتب نمط الحواشي العمل كاملًا عند أول استشهاد به في كل فصل. يُستعمل مع `bibliography.scope: 'chapter'`، فتأخذ قوائم الفصول أرقام فصولها. |
| `bibliography.title` | `string` | بحسب اللغة | العنوان فوق القائمة، فقرة بخط عريض. إن تُرك فارغًا فلا عنوان. والعنوان الذي تكتبه بنفسك يوضع فوق `:::bibliography`. |
| `bibliography.scope` | `'book' \| 'chapter'` | `'book'` | قائمة واحدة بكل عمل يستشهد به الكتاب، أو قائمة لكل فصل بالأعمال التي يستشهد بها. في المستند المؤلف من عدة فصول، يبدأ كل H1 قائمة فصل جديدة؛ ومع `auto` يحصل الفصل الذي لا يضع `:::bibliography` على قائمته في نهايته. |
| `bibliography.auto` | `boolean` | `true` | يضع القائمة بعد النص (في الفصل الأخير، للقائمة الشاملة للكتاب) حين لا تضعها أي `:::bibliography`. |
| `bibliography.fontSize` | `Dimension` | `0.9em` | حجم المُدخلات؛ وem هو حجم المتن. |
| `bibliography.lineHeight` | `Dimension` | تباعد أسطر المتن | تباعد أسطر المُدخلات. |
| `bibliography.hangingIndent` | `Dimension` | `2em` | إزاحة الأسطر التالية من المُدخل غير المرقّم. |
| `bibliography.entrySpacing` | `Dimension` | `0.3em` | المسافة بين مُدخلين. |
| `bibliography.labelWidth` | `Dimension` | أطول تسمية | عرض العمود الذي تقف فيه أرقام القائمة المرقّمة: يبدأ نص كل مُدخل على هذه المسافة إلى الداخل، في سطره الأول كما في أسطره التالية، فيتشارك `9.` و`10.` العمود. وتبقى التسمية جزءًا من نص المُدخل. |
| `bibliography.labelAlign` | `'left' \| 'right'` | `'left'` | موضع التسمية في عمودها: ملاصقة لحافته اليسرى، أو ملاصقة للنص (فينتهي `9.` و`10.` معًا). |
| `bibliography.doi` | `'link' \| 'text' \| 'hide'` | `'link'` | معرّفات DOI وعناوين URL روابطَ، أو نصًّا عاديًا، أو تُحذف. |
| `bibliography.includeUncited` | `boolean` | `false` | يُدرج كل مرجع، سواء استُشهد به أم لا (مثل `nocite: "@*"`). |
| `bibliography.groupByLanguage` | `boolean` | `false` | الأعمال المكتوبة بالصينية واليابانية والكورية أولًا، ثم الأخرى. لأنماط المؤلف والتاريخ والمؤلف والصفحة فقط: القائمة المرقّمة تحتفظ بترتيب أرقامها. |

## جدول المحتويات

تضبط الخاصية `toc` ما يطبعه التوجيه `:::toc` (انظر [صيغة المستند](https://postext.dev/ar/docs/document-format.md#toc)). تُجمَع المحتويات من **مخطّط** المستند (outline): كل عنوان برقمه وتسمية صفحته، وكل `:::part`؛ ولذلك تتبع الفصول: إن غيّرت اسم فصل، أو نقلته إلى جزء آخر، أو غيّرت مؤلفيه، تغيّرت المداخل معه. يتكوّن المدخل من رقم العنوان في عمود خاص به، ثم العنوان، ثم خط الإرشاد (leader) وتسمية الصفحة عند الحافة اليمنى، ثم سطر عنوان فرعي اختياري؛ أما الجزء فصفّ يصمّمه `parts.design`.

```ts
const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};
```

| الخاصية | النوع | القيمة الافتراضية | الوصف |
| --- | --- | --- | --- |
| `levels` | `TocLevelConfig[]` | المستوى 1 | مستويات العناوين المُدرَجة، ولكل منها تنضيد مدخله: `fontFamily`، `fontSize`، `lineHeight` (افتراضيًا تباعد أسطر المتن، فتستقر المحتويات على الشبكة)، `fontWeight`، `italic`، `color`، `indent` (للمدخل كله)، `numberWidth` / `numberGap` (عمود الرقم الذي يبدأ العنوان بعده؛ تُحاذى الأرقام فيه إلى اليمين، والرقم الأعرض من `numberWidth`، مثل `الفصل الحادي عشر` أو `Chapter 12`، يوسّع عمود مستواه إلى عرض أعرض الأرقام)، `numberFontFamily`، `numberFontSize`، `numberFontWeight`، `numberColor`، `marginTop`، `marginBottom`. الحقول غير المضبوطة ترث إعدادات نص المتن. يقع الرقم على خط أساس السطر الأول من العنوان، أيًّا كان محرفه وحجمه، على Canvas وفي HTML وفي PDF (حتى postext 1.4 كان الرقم يتوسّط ارتفاع الحرف x (x-height) مثل نقطة القائمة، فكان محرف العرض أو الحجم الأكبر يعلو فوق العنوان). يجد المُخرِج الذي تكتبه بنفسك خط الأساس هذا في `bulletBaselineY` من كتلة المدخل؛ وما زال `bulletY` منتصف مربّع em للرقم، كما في 1.4، فيرسم المُخرِج الأقدم من الحقل الجديد الأرقام حيث كان يرسمها دائمًا. |
| `unnumbered` | `TocEntryStyleConfig` | — | قيم بديلة للعناوين التي يحمل نمطها `numbered: false` (كالتمهيد): لا تطبع رقمًا وتبدأ محاذية لإزاحة `indent` الخاصة بالمستوى. |
| `pageNumber` | كائن | محرف المستوى 1، بوزن المتن | `fontFamily`، `fontSize`، `fontWeight`، `italic`، `color` لتسمية الصفحة، و`width` (افتراضيًا `2em`): العمود المحجوز لها عند الحافة اليمنى، حيث تُحاذى إلى اليمين. |
| `leader` | كائن | `{ enabled: true, char: '.', gap: 0.5em }` | يتكرّر `char` على امتداد الفراغ بين العنوان ورقم الصفحة، محاذى إلى اليمين لتصطفّ نقاط المداخل المتتالية (`'. '` يباعد بينها)؛ و`gap` أقل مسافة تُترك بين العنوان وخط الإرشاد. يأخذ خط الإرشاد من المحارف ما يتّسع له المكان، مقيسًا سلسلةً كاملة بمحرفه، فالمحرف الذي يباعد بين النقاط المتتالية بتقنين الأزواج (kerning) ينال نقاطًا أقل بدل نقاط تصل إلى رقم الصفحة. (حتى postext 1.4 كان العدد يُحسب من نقطة واحدة، وفي محرف كهذا كان خط الإرشاد يمتد من العنوان إلى داخل الرقم.) والعنوان الذي لا يترك للتسمية مكانًا يلتفّ أبكر قليلًا. ويُصفّ خط الإرشاد بثلاثة محارف أو أكثر: فإن لم يتّسع المكان إلا لمحرف أو اثنين بقي الصف بلا خط إرشاد، لأن نقطة مفردة قبل رقم الصفحة تُقرأ نقطةَ نهاية جملة. وفي PDF الموسوم تكون النقاط عناصر زخرفية من عناصر الإخراج، فلا تدخل في النص المستخرَج. ويضع نص المتن خطوط الإرشاد نفسها عند [مواضع الجدولة](https://postext.dev/ar/docs/configuration-text.md#مواضع-الجدولة). |
| `subtitle` | كائن | `{ enabled: false, attr: 'author' }` | سطر ثانٍ تحت المدخل مأخوذ من سمة في العنوان (`attr`)، أي مؤلفي الفصل، وله `fontFamily` و`fontSize` و`fontWeight` و`italic` (افتراضيًا `true`) و`color` خاصة به وإزاحة `indent` إضافية. يشارك السطر المدخل تباعد أسطره ولا ينفصل أبدًا عن عنوانه. |
| `parts.enabled` | `boolean` | `true` | هل تنال فواصل الأجزاء صفًّا. |
| `parts.breakBefore` | `boolean` | `false` | افتح صفحة جديدة قبل كل صف جزء ما عدا الأول، فتُدرَج فصول كل جزء في صفحة خاصة بها. |
| `parts.design` | `DesignSlot` | فارغ | تصميم الصف؛ حاويته هي الصف (عرض العمود × `height`). العناصر النائبة: `{number}`، `{numberDecimal}`، `{numberRoman}`…، `{titleText}` و`{pageNumber}` (تسمية صفحة الجزء؛ ومع `parts.page: false`، الذي لا يفتح صفحة جزء، تسمية الصفحة التي يبدأ عليها محتوى الجزء، حيث تنتقل الترويسات إليه؛ وفي كتاب يُخرَج فصلًا فصلًا، يشير السياج الذي يُغلق فصله إلى أول صفحة محتوى في الفصل التالي). تأخذ الألوان المرتبطة بلوحة الألوان قيمَ `palette` الخاصة بالجزء، فيأتي صف كل قسم بلونه. وحين يكون التصميم فارغًا، يُنضَّد `{number} {titleText}` (وبينهما `numberSeparator` الخاص بعنوان H1) ورقم الصفحة بتنضيد مدخل المستوى 1. |
| `parts.height`، `marginTop`، `marginBottom` | `Dimension` | `2em`، `0`، `0` | ارتفاع الصف والمسافة حوله. وحدة `em` هي حجم نص المتن، فارتفاع الصف الافتراضي ضعف حجم المتن، لا سطران من المتن: مع متن 9.5/13.5 pt يكون 19 pt. ولصفّ بارتفاع سطرين من المتن، أعطِ الارتفاع بوحدة `pt` (`27pt` في ذلك المثال). |

تسميات الصفحات هي التي يطبعها المستند. يعيد `buildDocument()` إخراج المستند الذي يحوي `:::toc` بتسميات الجولة السابقة حتى تستقر (ثلاث جولات إضافية على الأكثر)؛ أما المضيف الذي يُخرج كتابًا فصلًا فصلًا فيقدّم بدلًا من ذلك مخطّط الكتاب كله في `PostextContent.outline`، مجمَّعًا من `contentOutline()` (العناوين والأجزاء من النص وحده) و`outlineFromDoc()` (المداخل نفسها بتسميات الصفحات في إخراجٍ ما)، ويعيد إخراج فصل المحتويات كلما تغيّر `outlineKey()` لذلك المخطّط. يحمل كل مدخل عنوانٍ الرقمَ `number` الذي تطبعه المحتويات، ويحمل العنوان المرقّم كذلك `counter` الخاص به: العدّ الجاري لمستواه بعد أي `startAt`، أيًّا كان ما يطبعه القالب، وهو ما يعرضه المضيف بجانب الفصل في قوائمه الخاصة.

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

تضبط الخاصية `index` ما يطبعه التوجيه `:::index` (انظر [صيغة المستند](https://postext.dev/ar/docs/document-format.md#الفهرس-الأبجدي)): المصطلحات المعلَّمة بـ `:index[…]` و`:index{term="…"}` في النص، مرتّبةً ومجمّعةً حسب الحرف الأول (وفي الصينية حسب الحرف الأول من قراءة pinyin أو حسب عدد الضربات، وفي اليابانية حسب صف غوجوون، انظر `groupBy`)، ولكل منها الصفحات التي يقع فيها. يتكوّن المدخل من مصطلحه، ففاصل، فأرقام صفحاته؛ وتليه مداخله الفرعية، بخطوة إزاحة واحدة لكل مستوى، وتتدلّى أسطره الملتفّة بمقدار `turnoverIndent` فلا تصطفّ أبدًا مع مدخل فرعي.

```ts
const config: PostextConfig = {
  headingStyles: [
    // The index in two columns, under its own heading.
    { id: 'index', numbered: false, layout: { layoutType: 'double', gutterWidth: { value: 6, unit: 'mm' } } },
  ],
  index: {
    fontSize: { value: 8.5, unit: 'pt' },
    lineHeight: { value: 11, unit: 'pt' },
    rangeFormat: 'chicago',
    groups: { fontFamily: 'Source Sans 3', fontWeight: 700, color: { hex: '#8a1c1c', model: 'hex' } },
  },
};
```

| الخاصية | النوع | القيمة الافتراضية | الوصف |
| --- | --- | --- | --- |
| `fontFamily`، `fontSize`، `lineHeight`، `fontWeight`، `color` | — | نص المتن | تنضيد المداخل. كل سطر في الفهرس، بما فيه رؤوس الحروف، يُنضَّد على `lineHeight`؛ للفهرس إيقاعه الخاص ولا يلتزم بشبكة خطوط الأساس. |
| `indent` | `Dimension` | `1em` | إزاحة كل مستوى من المداخل الفرعية. |
| `turnoverIndent` | `Dimension` | `2em` | إزاحة إضافية للأسطر الملتفّة من المدخل، فوق إزاحة مستواه. |
| `entrySpacing` | `Dimension` | `0` | المسافة فوق كل مدخل رئيسي. |
| `separator`، `locatorSeparator`، `rangeSeparator` | `string` | `', '`، `', '`، `'–'`؛ والأوّلان `'، '` في الخط العربي | ما يُطبع بين المصطلح وأول صفحة له، وبين صفحتين، وبين طرفي النطاق. |
| `mergeRanges` | `boolean` | `true` | اضمم الصفحات المتتالية ذات صيغة الترقيم الواحدة في نطاق: `12, 13, 14` تُطبع `12–14`. لا تُضمّ الصفحات الرئيسية أبدًا. |
| `rangeFormat` | `'full' \| 'chicago'` | `'full'` | كيف يُكتب الرقم الثاني في النطاق: كاملًا (`234–237`)، أو بحذف الأرقام التي يشترك فيها مع الأول، كما يطلب *The Chicago Manual of Style* (9.64): `71–72`، `100–104`، `101–8`، `321–28`، `1496–500`. التسميات الرومانية تُكتب كاملة دائمًا. |
| `main` | `{ bold?, italic? }` | عريض | كيف تُنضَّد الصفحة الرئيسية (`main` على العلامة). |
| `see` | `{ label?, alsoLabel?, italic? }` | حسب اللغة، مائل (قائم في الخط العربي) | الكلمات التي تسبق الإحالة. إن لم تُضبط تتبع لغة المستند: *See* / *See also*، *Véase* / *Véase también*، *Voir* / *Voir aussi*، 见 / 另见 (見 / 另見 في الصينية التقليدية)… يضع الفهرس الصيني الإحالة بعد نقطة، بلا مسافة: `贾琏 12。见贾政`. |
| `locale` | `string` | لغة المستند | اللغة التي يُرتَّب بترتيبها الأبجدي المداخل (وسم BCP 47 يقرؤه `Intl.Collator`). في الإسبانية تأتي *ñ* بعد *n* وتتصدّر مجموعة خاصة بها؛ ولا تغيّر العلامات فوق الحروف (accents) الترتيب أبدًا. |
| `groupBy` | `'auto' \| 'letter' \| 'pinyin' \| 'stroke' \| 'gojuon' \| 'kana' \| 'none'` | `'auto'` | ما تكونه رؤوس المجموعات. `'letter'`: الحرف الأول من مفتاح الترتيب. `'pinyin'`: المدخل الذي يبدأ بمقطع صيني (Han) يُصنَّف تحت الحرف اللاتيني الأول من قراءته بالـ pinyin (贾宝玉 تحت `J`)، ومفتاح الترتيب اللاتيني تحت حرفه، بعد المداخل الصينية لذلك الحرف (إذ يضع المرتِّب الحروف اللاتينية بعد المقاطع الصينية): `sort="jia mu"` يُختَم به حرف `J`. `'stroke'`: تحت عدد ضربات المقطع الأول، `一畫`، `二畫`… (`一画`… في الصينية المبسّطة). `'gojuon'`: يُصنَّف مدخل الكانا تحت صف غوجوون الخاص به، あ行، か行 … わ行، و`'kana'` تحت أول حرف كانا فيه (وتتشارك الكاتاكانا والهيراغانا الرؤوس)، بترتيب JIS X 4061 للفهرس الياباني: حسب القراءة (`yomi` في العلامة، وإلا قراءة الكانا في الروبي الذي فيها، وإلا `sort`، وإلا النص)، والكاتاكانا كالهيراغانا، والكانا الصغيرة كالكبيرة، و ー كالحرف الصوتي الذي قبلها، وغير المجهور (清) قبل المجهور (濁) قبل شبه المجهور (半濁)؛ الرموز أولًا، ثم الأرقام حسب قيمتها، ثم الكلمات اللاتينية تحت حروفها، ثم الكانا؛ والمدخل الذي ما زال يبدأ بكانجي يُبلَّغ عنه بالتحذير `indexReadingMissing` ويُنضَّد بعد الكانا بلا رأس. `'none'`: بلا رؤوس؛ تُفصَل الرموز والأرقام والكلمات بمسافة `groups.marginTop` وحدها. أما `'auto'` فيجمّع الفهرس الياباني (`ja`، `ja-*`) حسب صف غوجوون، والفهرس الصيني المبسّط (`zh`، `zh-Hans`، `zh-CN`) حسب pinyin، والتقليدي (`zh-Hant`، `zh-TW`، `zh-HK`) حسب الضربات، وكل لغة أخرى حسب الحرف. تُرتَّب المداخل بالترتيب الذي تأتي منه الرؤوس: فالفهرس `zh-Hant` المجمَّع حسب pinyin يُرتَّب حسب pinyin. القراءات وأعداد الضربات هي ما يعطيه المرتِّب (CLDR)؛ وحيث يقرأ مقطعًا قراءة خاطئة (重 بقراءة *zhòng* في 重阳، و行 بقراءة *xíng* في 行业)، أعطِ العلامة مفتاح `sort` بمقاطع ليس لها إلا القراءة التي تريدها، فيُرتَّب المدخل في موضعه: `sort="崇阳"` لـ 重阳، و`sort="航业"` لـ 行业. والمتصفح الذي لا يملك بيانات الترتيب الصيني يطبع فهرس pinyin أو فهرس الضربات بلا رؤوس. |
| `ignoreArticle` | `boolean` | `true` في العربية | رتّب المداخل العربية وجمّعها كأن أداة التعريف `ال` (`ٱل`) في أولها غير موجودة: تُصنَّف البصرة تحت ب، بين بدر وبغداد، وتُطبع كما كُتبت. تحتفظ `الله` بأداة التعريف، والمدخل الذي له مفتاح `sort` خاص يُرتَّب بذلك المفتاح كما هو. وأيًّا كانت قيمة هذا الإعداد، يتجاهل الفهرس العربي الحركات والتطويل، ويصنّف أ إ آ ٱ تحت ا، ويرتّب ؤ كما يرتّب و، وئ وى كما يرتّب ي، وة كما يرتّب ه. |
| `groups.enabled` | `boolean` | `true` | اطبع رأسًا فوق كل مجموعة من المداخل (`A`، `B`…، أو عدد الضربات، و`0–9` للأرقام، و`Symbols` للبقية؛ و`数字` / `數字` و`符号` / `符號` في الصينية). |
| `groups.fontFamily`، `fontSize`، `fontWeight`، `italic`، `color` | — | ما للمداخل، والوزن `700` | محرف رأس الحرف. يُنضَّد على خطوة أسطر المداخل. |
| `groups.marginTop` | `Dimension` | سطر واحد من الفهرس | المسافة فوق كل مجموعة، برأس أو بدونه؛ ولا مسافة فوق المجموعة الأولى، التي تحدّد بُعدَها عن العنوان مسافةُ العنوان نفسه، ولا في أعلى العمود. |
| `groups.symbolsLabel`، `numbersLabel` | `string` | حسب اللغة؛ `'0–9'`، و`'数字'` / `'數字'` في الصينية | رأسا المداخل التي تبدأ برمز والتي تبدأ برقم. |

تأتي أرقام الصفحات من مخطّط الكتاب، كما تأتي أرقام المحتويات: يُدرج `computeOutline()` و`contentOutline()` علامات الفهرس في النص مداخلَ من النوع `'indexMark'` (مع `indexMark.path` و`sort` و`see` و`seeAlso` و`main` و`range` و`index`)، ويعطي `outlineFromDoc()` كلًّا منها الصفحة التي وقعت عليها، وهي ما يسجّله البناء في `doc.indexMarks` (`{ sourceStart, pageIndex }` لكل علامة). يعيد `buildDocument()` إخراج المستند الذي يطبع فهرسه بنفسه حتى تستقر الأرقام؛ أما المضيف الذي يُخرج كتابًا فصلًا فصلًا فيسلّم الفصلَ الذي يحوي `:::index` مخطّطَ الكتاب كله في `PostextContent.outline`. يقسم `tocOutline()` و`indexOutline()` المخطّط إلى ما تقرؤه المحتويات وما يقرؤه الفهرس، ليتمكّن المضيف من ربط كل فصل بالجزء الذي يطبعه: فلا يعيد Sandbox إخراج فصل الفهرس إلا حين تتحرّك علامة، ولا فصل المحتويات إلا حين يتحرّك عنوان. ويخبر `contentOutline()` كذلك هل يطبع النص فهرسًا (`hasIndex`).