# صفحة على طريقة بولاق: المتن يحيط به شرحه

> شرح ابن عقيل في العمود الرئيسي، والحواشي في العمود الجانبي الخارجي بجانب المواضع التي تشرحها، والكل داخل إطار من خطين.

- نسخة HTML: https://postext.dev/ar/cookbook/bulaq-framed-page
- وصفة رقم 114 · الصفحة والشبكة · المستوى 2 (متوسط) · المخرجات: Canvas, PDF
- الأنواع: الكتب المدرسية
- تتطلب postext ≥ 1.15.0, postext-pdf ≥ 1.15.0 · اختُبرت مع 1.15.0, postext-pdf 1.15.0 بتاريخ 2026-10-04
- الصفحات: [١](https://postext.dev/cookbook/bulaq-framed-page/en/p01.webp?v=ea0ee764), [٢](https://postext.dev/cookbook/bulaq-framed-page/en/p02.webp?v=ea0ee764), [٣](https://postext.dev/cookbook/bulaq-framed-page/en/p03.webp?v=ea0ee764), [٤](https://postext.dev/cookbook/bulaq-framed-page/en/p04.webp?v=ea0ee764), [٥](https://postext.dev/cookbook/bulaq-framed-page/en/p05.webp?v=ea0ee764), [٦](https://postext.dev/cookbook/bulaq-framed-page/en/p06.webp?v=ea0ee764)
- PDF: https://postext.dev/cookbook/bulaq-framed-page/en/bulaq-framed-page.pdf?v=ea0ee764
- افتح في Sandbox: https://postext.dev/ar/sandbox#recipe=bulaq-framed-page&lang=en (.postext: https://postext.dev/cookbook/bulaq-framed-page/en/bulaq-framed-page.postext)
- آخر تحديث: 2026-10-04
- لغات أخرى: [en](https://postext.dev/en/cookbook/bulaq-framed-page.md), [es](https://postext.dev/es/cookbook/bulaq-framed-page.md), [ca](https://postext.dev/ca/cookbook/bulaq-framed-page.md), [zh](https://postext.dev/zh/cookbook/bulaq-framed-page.md)

## باختصار

صفحة مصنوعة على هيئة الكتب العربية التي طُبعت في القاهرة في القرن التاسع عشر: المتن في الوسط، وتعليقات قصيرة عليه في عمود ضيق عند الحافة، والصفحة كلها محصورة في خطوط مطبوعة.

## ما الذي ستنضده

ست صفحات منضّدة كما كانت مطبعة بولاق ومن خلفها من مطابع القاهرة تطبع الشروح في القرن التاسع عشر. يجري شرح ابن عقيل لأول أبيات الألفية، منظومة ابن مالك في النحو في ألف بيت، في العمود الرئيسي، والأبيات بالأحمر؛ وفي الهامش الخارجي حاشية، تعليقات قصيرة تبدأ كل منها بألفاظ المتن الذي تشرحه، بجانب الموضع الذي تتعلق به. يحيط خطان مزدوجان بمساحة النص، في رأسها شريط لعنوان الباب ورقم الصفحة، ويفصل خط مفرد المتن عن هامشه. في صفحة بولاق الحقيقية تلتف الحاشية حول المتن من ثلاث جهات؛ أما Postext فينضّدها في جهة واحدة فقط، وهذه الوصفة تقول ذلك.

**تجيب هذه الوصفة عن:**

- كيف أُخرج صفحة على طريقة بولاق، يحيط فيها الشرح بالمتن داخل إطار؟

## الجواب المختصر

```js
// script.js, سطرًا 31–43
// The text runs in the main column of a column-and-a-half layout; the side column, on the
// outer side, takes only boxes with span 'side', so each gloss stands level with the
// paragraph it comments on. A column rule parts the two, as the jadwal of a Bulaq page does.
const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
  sideColumnPercent: 31, gutterWidth: mm(7),
  columnRule: { enabled: true, color: col('rule'), lineWidth: pt(0.6) } };
// A gloss is a callout with no box: the margin's own face, its lemma bold in the rubric.
const hashiya = { id: 'hashiya', span: 'side', backgroundEnabled: false, borderRadius: pt(0),
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  stripe: { enabled: false }, border: { enabled: false },
  body: { fontFamily: NASKH, fontSize: pt(10), lineHeight: pt(16), color: col('ink'),
    boldColor: col('rubric'), textAlign: 'justify', firstLineIndent: pt(0),
    paragraphSpacing: true } };
```

## المكونات

**تعلّم**

- [ملاحظات الهامش](https://postext.dev/ar/docs/configuration.md#أنماط-الإطارات): إطارات توضع في العمود الجانبي بمحاذاة الفقرة التي تشرحها، في تخطيط عمود ونصف مع قناة للعناصر العائمة.
- [النصوص والخطوط والمربعات في تصاميم الصفحة](https://postext.dev/ar/docs/configuration.md#رؤوس-الصفحات-وتذييلاتها): عناصر الرسم المشتركة بين الرؤوس والتذييلات وصفحات الافتتاح وصفحات الأجزاء: نص بكبسولة اختيارية، وخطوط أفقية وعمودية، ومربعات مملوءة أو مؤطَّرة تُرسم بترتيب المصفوفة.
- [النص من اليمين إلى اليسار](https://postext.dev/ar/docs/arabic-layout.md#الاتجاه-وخوارزمية-النص-ثنائي-الاتجاه): يحدّد direction الاتجاه الأساسي للمستند: تأخذه القيمة 'auto' (الافتراضية) من نظام كتابة locale، فتجري 'ar' و'fa' و'he' من اليمين إلى اليسار؛ وترتّب الخوارزمية ثنائية الاتجاه (UAX #9) الكلمات اللاتينية والأرقام داخل كل سطر، ويُجلَّد الكتاب من اليمين.

**تستخدم أيضًا**

- [عمود ونصف](https://postext.dev/ar/docs/configuration.md#أنواع-التخطيط)
- [عمود هامشي للعناصر العائمة](https://postext.dev/ar/docs/configuration.md#التخطيط)
- [الخط الفاصل بين الأعمدة](https://postext.dev/ar/docs/configuration.md#الخط-الفاصل-بين-الأعمدة)
- [كتب مجلّدة من اليمين](https://postext.dev/ar/docs/configuration.md#التجليد)
- [الخطوط العربية](https://postext.dev/ar/docs/arabic-layout.md#الخطوط)
- [العربية لغةً للمستند](https://postext.dev/ar/docs/arabic-layout.md#البدء-بكتاب-عربي)
- [الشعر العربي (البيت بشطرين)](https://postext.dev/ar/docs/document-format.md#verse)
- [أشكال الأرقام في الأعداد المولَّدة](https://postext.dev/ar/docs/configuration.md#لغة-المستند)
- [الأغلفة وصفحات العنوان وبيانات النشر](https://postext.dev/ar/docs/configuration.md#أنماط-العناوين)
- [أنماط العناوين](https://postext.dev/ar/docs/configuration.md#أنماط-العناوين)
- [سمات العنوان](https://postext.dev/ar/docs/document-format.md#سمات-العناوين)
- [الترويسات وأرقام الصفحات](https://postext.dev/ar/docs/configuration.md#رؤوس-الصفحات-وتذييلاتها)
- [لون الورق](https://postext.dev/ar/docs/configuration.md#الصفحة)
- [أنماط الفقرات](https://postext.dev/ar/docs/configuration.md#أنماط-الفقرات)
- [فقرات بالاتجاه المعاكس](https://postext.dev/ar/docs/arabic-layout.md#اتجاه-المستند-والكتلة-والنص-داخل-السطر)
- [لوحة ألوان دلالية](https://postext.dev/ar/docs/configuration.md#لوحة-الألوان)
- [التصدير إلى PDF](https://postext.dev/ar/docs/configuration.md#توليد-ملفات-pdf)
- [إطارات التنبيه](https://postext.dev/ar/docs/configuration.md#أنماط-الإطارات)
- [صفحات افتتاح مصمَّمة](https://postext.dev/ar/docs/configuration.md#الامتداد-والتصميم-المتقدم)
- [الترويسات بحسب دور الصفحة](https://postext.dev/ar/docs/configuration.md#عناصر-النص)
- [الخطوط المضمَّنة في PDF](https://postext.dev/ar/docs/configuration.md#لماذا-مزوّد-الخطوط)
- [ترويسات لكل قسم](https://postext.dev/ar/docs/configuration.md#أنماط-العناوين)

**الإعدادات في لمحة**

- [`bodyText`](https://postext.dev/ar/docs/configuration.md#نص-المتن), [`calloutStyles`](https://postext.dev/ar/docs/configuration.md#أنماط-الإطارات), [`colorPalette`](https://postext.dev/ar/docs/configuration.md#لوحة-الألوان), [`footer`](https://postext.dev/ar/docs/configuration.md#رؤوس-الصفحات-وتذييلاتها), [`header`](https://postext.dev/ar/docs/configuration.md#رؤوس-الصفحات-وتذييلاتها), [`headingStyles`](https://postext.dev/ar/docs/configuration.md#أنماط-العناوين), [`headings`](https://postext.dev/ar/docs/configuration.md#العناوين), [`layout`](https://postext.dev/ar/docs/configuration.md#التخطيط), [`locale`](https://postext.dev/ar/docs/configuration.md#تقسيم-الكلمات-بالواصلة), [`page`](https://postext.dev/ar/docs/configuration.md#الصفحة), [`paragraphStyles`](https://postext.dev/ar/docs/configuration.md#أنماط-الفقرات)

**واجهات API**

- [`buildDocument`](https://postext.dev/ar/docs/configuration.md#بناء-مستند), [`clearMeasurementCache`](https://postext.dev/ar/docs/configuration.md#ذاكرة-القياس-المؤقتة), [`decompressWoff2`](https://postext.dev/ar/docs/configuration.md#مزوّد-الخطوط-في-المتصفح-fontsource--woff2), [`renderPageToCanvas`](https://postext.dev/ar/docs/configuration.md#رسم-صفحة-في-صورة-نقطية), [`renderToPdf`](https://postext.dev/ar/docs/configuration.md#توليد-ملفات-pdf)

**الخطوط**

- Amiri (OFL-1.1), Aref Ruqaa (OFL-1.1)

## طريقة التحضير

### 1 · الحاشية في عمود جانبي خاص بها

الكود هو [الجواب المختصر](#الجواب-المختصر) أعلاه. تخطيط العمود والنصف الذي لا يأخذ عموده الجانبي إلا العناصر العائمة يُبقي الشرح خارج مجرى المتن: كل تعليق `:::callout{type="hashiya" span="side"}` مكتوب بعد الفقرة التي يشرحها، ويقف بمحاذاة تلك الفقرة ([التخطيط](/ar/docs/configuration#التخطيط)). لا خلفية للإطار ولا حدود ولا حشوة، فيُقرأ نصًا منضّدًا في الهامش، ولفظ المتن فيه غامق، يجعله `boldColor` أحمر. ويضع `sideColumnSide: 'outer'` العمود عند الحافة الأمامية في الصفحتين: على يمين الصفحة الزوجية، الواقعة على اليمين في كتاب مجلّد على اليمين.

![Page ٣.](https://postext.dev/cookbook/bulaq-framed-page/en/p03.webp?v=ea0ee764)

*الصفحة 3: الحاشية على «كديز» بجانب الفقرة التي تستعمل الكلمة، عند الحافة الخارجية، خلف الخط الفاصل بين العمودين.*

### 2 · إطار يُرسم لكل جانب من الصفحتين المتقابلتين

```js
// script.js, سطرًا 47–73
// Page-level design elements are physical: the frame follows the margins of each side of
// the spread. In a book bound on the right the even page is the right-hand one, its spine
// on its left, so its inner margin is the left one.
const frame = (parity, withBand = true) => {
  const left = parity === 'even' ? M.inner : M.outer;
  const width = TRIM.width - M.inner - M.outer;
  const box = (id, inset, thickness) => ({ kind: 'box', id: `${id}-${parity}`, parity,
    style: { borderColor: col('rule'), borderWidth: pt(thickness) },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      offset: { x: mm(left - 4 + inset), y: mm(M.top - 13 + inset) },
      size: { width: mm(width + 8 - 2 * inset),
        height: mm(TRIM.height - M.top - M.bottom + 17 - 2 * inset) } } });
  return [box('outer', 0, 1.4), box('inner', 1.3, 0.4), ...(withBand ? [
    { kind: 'rule', id: `band-${parity}`, parity, direction: 'horizontal', thickness: pt(0.4),
      color: col('rule'), placement: { anchor: { to: 'page', edge: 'top-left' },
        offset: { x: mm(left - 2.7), y: mm(M.top - 4) },
        size: { width: mm(width + 5.4) } } }] : [])];
};
// The chapter centred in the band, the folio at its outer end.
const band = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: NASKH, fontWeight: 700, fontSize: pt(10.5),
  color: col('ink'),
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(M.top - 11) } }, ...extra });
const header = { elements: [...frame('even'), ...frame('odd'),
  band('head', '{chapterTitle}', 'all', 'top', 0),
  band('folio-even', '{pageNumber}', 'even', 'top-right', -(M.outer + 1), { pages: 'all' }),
  band('folio-odd', '{pageNumber}', 'odd', 'top-left', M.outer + 1, { pages: 'all' })] };
```

الإطار ثلاثة عناصر من عناصر تصميم الصفحة في الترويسة: صندوقان بحدود ودون تعبئة، بينهما 1.3 مم، وخط تحت الشريط الذي يحمل الترويسة. عناصر الصفحة فعلية الجوانب، فيُبنى الإطار مرتين، مرة لكل زوجية وفردية، من هوامش ذلك الجانب ([ترتيب الصفحات والتجليد على اليمين](/ar/docs/arabic-layout#ترتيب-الصفحات-والتجليد-على-اليمين)). يقع رقم الصفحة عند الطرف الخارجي من الشريط في كل صفحة، وصفحات الافتتاح منها؛ وعنوان الباب موسّط ويُترك من صفحة الافتتاح، حيث يقف العنوان نفسه تحته.

### 3 · صفحة عنوان داخل الإطار نفسه

```js
// script.js, سطرًا 77–94
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'),
  placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) },
    size: { width: mm(110) } }, ...style });
const titlePage = { id: 'title', span: 'page', runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
  footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [...frame('odd', false),
    line('book', '{titleText}', 64, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(40),
      lineHeight: 1.3, color: col('rubric') }),
    line('on', '{attr.on}', 88, { fontFamily: NASKH, fontWeight: 700, fontSize: pt(17) }),
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.75), color: col('rubric'),
      placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(104) },
        size: { width: mm(30) } } },
    line('margin', '{attr.margin}', 112, { fontFamily: NASKH, fontSize: pt(13) }),
    line('latin', '{attr.latin}', 196, { fontFamily: NASKH, fontSize: pt(9), italic: true,
      color: col('muted') }),
  ] } } };
```

تعيد صفحة العنوان استعمال الإطار دون شريطه. تأتي أسطرها من سمات العنوان، `on` و`margin`، فتكون صفحة العنوان كلها سطرًا واحدًا في Markdown، والسطر اللاتيني تحتها يتغير مع الطبعة.

## الوصفة كاملة

ملف واحد، مركّب من مجلد الوصفة ومعه نص المثال وأدوات دليل الوصفات المشتركة مضمّنة؛ وهو ينشئ صفحته بنفسه. لتشغيله، ضعه داخل `<script type="module">` في صفحة فارغة أو الصقه في لوحة JS في مثال CodePen جديد (وحدةً). يستورد postext من esm.sh، فلا حاجة إلى تثبيت أو بناء.

- مجلد الوصفة: https://github.com/drnachio/postext/tree/main/cookbook/bulaq-framed-page

### script.js

```js
// ═══ Postext Cookbook · Nº 114 · A Bulaq page: the text framed by its commentary ════════
// https://postext.dev/en/cookbook/bulaq-framed-page
// Code: MIT · Text: Ibn ʿAqīl, Sharḥ; Ibn Mālik, Alfiyya, ar.wikisource (PD) · Pictures: none
// Fonts: Amiri, Aref Ruqaa (SIL OFL 1.1) · Needs postext ≥ 1.15.0
import { buildDocument, renderPageToCanvas, clearMeasurementCache } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'bulaq-framed-page';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Black and a brown-red on a toned paper: the two inks of a Cairo press around 1900.
const palette = {
  ink: '#1d1915', // text and frame rules
  rubric: '#8e3020', // the accent: lemmas of the glosses, the matn, titles
  rule: '#3a312a', // the frame
  muted: '#6a6056', // the note on the text
  paper: '#f6efe0', // a toned paper
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  { id: 'main-color', name: 'rubric (defaults)', value: { hex: palette.rubric, model: 'hex' } },
];
const NASKH = 'Amiri'; // the text, the matn and the glosses
const RUQAA = 'Aref Ruqaa'; // the title page and the chapter title
const TRIM = { width: 170, height: 240 }; // mm
const M = { top: 34, bottom: 24, inner: 20, outer: 15 }; // mm: the type area inside the frame

// #region answer: the commentary's column beside the text, both inside one ruled frame
// The text runs in the main column of a column-and-a-half layout; the side column, on the
// outer side, takes only boxes with span 'side', so each gloss stands level with the
// paragraph it comments on. A column rule parts the two, as the jadwal of a Bulaq page does.
const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
  sideColumnPercent: 31, gutterWidth: mm(7),
  columnRule: { enabled: true, color: col('rule'), lineWidth: pt(0.6) } };
// A gloss is a callout with no box: the margin's own face, its lemma bold in the rubric.
const hashiya = { id: 'hashiya', span: 'side', backgroundEnabled: false, borderRadius: pt(0),
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  stripe: { enabled: false }, border: { enabled: false },
  body: { fontFamily: NASKH, fontSize: pt(10), lineHeight: pt(16), color: col('ink'),
    boldColor: col('rubric'), textAlign: 'justify', firstLineIndent: pt(0),
    paragraphSpacing: true } };
// #endregion

// #region frame: a double rule round the type area and a band for the running head
// Page-level design elements are physical: the frame follows the margins of each side of
// the spread. In a book bound on the right the even page is the right-hand one, its spine
// on its left, so its inner margin is the left one.
const frame = (parity, withBand = true) => {
  const left = parity === 'even' ? M.inner : M.outer;
  const width = TRIM.width - M.inner - M.outer;
  const box = (id, inset, thickness) => ({ kind: 'box', id: `${id}-${parity}`, parity,
    style: { borderColor: col('rule'), borderWidth: pt(thickness) },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      offset: { x: mm(left - 4 + inset), y: mm(M.top - 13 + inset) },
      size: { width: mm(width + 8 - 2 * inset),
        height: mm(TRIM.height - M.top - M.bottom + 17 - 2 * inset) } } });
  return [box('outer', 0, 1.4), box('inner', 1.3, 0.4), ...(withBand ? [
    { kind: 'rule', id: `band-${parity}`, parity, direction: 'horizontal', thickness: pt(0.4),
      color: col('rule'), placement: { anchor: { to: 'page', edge: 'top-left' },
        offset: { x: mm(left - 2.7), y: mm(M.top - 4) },
        size: { width: mm(width + 5.4) } } }] : [])];
};
// The chapter centred in the band, the folio at its outer end.
const band = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: NASKH, fontWeight: 700, fontSize: pt(10.5),
  color: col('ink'),
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(M.top - 11) } }, ...extra });
const header = { elements: [...frame('even'), ...frame('odd'),
  band('head', '{chapterTitle}', 'all', 'top', 0),
  band('folio-even', '{pageNumber}', 'even', 'top-right', -(M.outer + 1), { pages: 'all' }),
  band('folio-odd', '{pageNumber}', 'odd', 'top-left', M.outer + 1, { pages: 'all' })] };
// #endregion

// #region title: the title page, framed like the text pages
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'),
  placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) },
    size: { width: mm(110) } }, ...style });
const titlePage = { id: 'title', span: 'page', runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
  footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [...frame('odd', false),
    line('book', '{titleText}', 64, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(40),
      lineHeight: 1.3, color: col('rubric') }),
    line('on', '{attr.on}', 88, { fontFamily: NASKH, fontWeight: 700, fontSize: pt(17) }),
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.75), color: col('rubric'),
      placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(104) },
        size: { width: mm(30) } } },
    line('margin', '{attr.margin}', 112, { fontFamily: NASKH, fontSize: pt(13) }),
    line('latin', '{attr.latin}', 196, { fontFamily: NASKH, fontSize: pt(9), italic: true,
      color: col('muted') }),
  ] } } };
// #endregion

const config = () => ({ // a factory: the engine caches resolved configs per object
  locale: 'ar', // right to left, bound on the right, digits ٠–٩ (gotcha: arabic-locale-tag)
  colorPalette,
  page: { width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
    backgroundColor: col('paper'), margins: { top: mm(M.top), bottom: mm(M.bottom),
      left: mm(M.inner), right: mm(M.outer), mirror: true } },
  layout,
  bodyText: { fontFamily: NASKH, fontSize: pt(12.5), lineHeight: pt(22), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'justify', firstLineIndent: em(1.2), indentAfterHeading: false,
    optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true },
  // Restated: any headings object drops the H1 break (gotcha: headings-drop-h1-break).
  headings: { fontFamily: RUQAA, fontWeight: 700, color: col('rubric'), textAlign: 'center',
    levels: [{ level: 1, fontSize: pt(22), lineHeight: pt(32), marginTop: pt(0),
      marginBottom: pt(8), breakBefore: { enabled: true, parity: 'any' } }] },
  headingStyles: [titlePage],
  calloutStyles: [hashiya],
  paragraphStyles: [
    // The matn's bayts: bold and in the rubric, as Ibn ʿAqīl's printers set the Alfiyya.
    { id: 'matn', fontFamily: NASKH, fontWeight: 700, fontSize: pt(12.5),
      lineHeight: pt(23), color: col('rubric'), marginTop: pt(4), marginBottom: pt(6) },
    { id: 'note', fontFamily: NASKH, fontSize: pt(9), lineHeight: pt(13), color: col('muted'),
      boldColor: col('ink'), textAlign: 'justify', firstLineIndent: pt(0), marginTop: pt(10),
      hyphenation: { enabled: true, locale: LANG } },
    { id: 'colophon', fontFamily: NASKH, fontSize: pt(7.5), lineHeight: pt(10),
      color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(6) },
  ],
  header, footer: { elements: [] },
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`---
title: "شرح ابن عقيل"
subtitle: "الكلام وما يتألف منه"
---

# شرح ابن عقيل {style="title" on="على ألفية ابن مالك" margin="وبهامشه حواشٍ على مواضع منه" latin="Ibn ʿAqīl’s commentary on the Alfiyya of Ibn Mālik, with glosses in its margin"}

# الكلام وما يتألف منه

بسم الله الرحمن الرحيم، الحمد لله وحده، وصلاته وسلامه على من لا نبي بعده.

:::verse{style="matn"}
قال محمد هو ابن مالك || أحمد ربي الله خير مالك
مصليا على النبي المصطفى || وآله المستكملين الشرفا
وأستعين الله في ألفيه || مقاصد النحو بها محويه
تقرب الأقصى بلفظ موجز || وتبسط البذل بوعد منجز
وتقتضي رضا بغير سخط || فائقة ألفية ابن معط
وهو بسبق حائز تفضيلا || مستوجب ثنائي الجميلا
والله يقضي بهبات وافره || لي وله في درجات الآخره
:::

:::callout{type="hashiya" span="side"}
**قوله «ابن مالك»:** هو جمال الدين محمد بن عبد الله بن مالك الطائي الجيّاني، وُلد بجيّان من بلاد الأندلس، ونزل دمشق وبها توفي سنة اثنتين وسبعين وستمئة.

**قوله «ألفية ابن معط»:** هي الدرّة الألفية ليحيى بن عبد المعطي الزواوي، المتوفى بالقاهرة سنة ثمان وعشرين وستمئة، وهي أسبق من ألفية ابن مالك، ولذلك قال: «وهو بسبق حائز تفضيلا».
:::

:::verse{style="matn"}
كلامنا لفظ مفيد كاستقم || واسم وفعل ثم حرف الكلم
واحده كلمة والقول عم || وكلمة بها كلام قد يؤم
:::

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

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

:::callout{type="hashiya" span="side"}
**قوله «كديز»:** لفظ لا معنى له في كلام العرب، يمثّل به النحاة للمهمل، كما يمثّلون بزيد وعمرو للمستعمل.
:::

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

والكلمة هي اللفظ الموضوع لمعنى مفرد، فقولنا «الموضوع لمعنى» أخرج المهمل كديز، وقولنا «مفرد» أخرج الكلام، فإنه موضوع لمعنى غير مفرد. ثم ذكر المصنف رحمه الله تعالى أن القول يعم الجميع، والمراد أنه يقع على الكلام أنه قول، ويقع أيضا على الكلم والكلمة أنه قول. ثم ذكر أن الكلمة قد يُقصد بها الكلام، كقولهم في «لا إله إلا الله»: كلمة الإخلاص.

:::verse{style="matn"}
بالجر والتنوين والندا وأل || ومسند للاسم تمييز حصل
:::

ذكر المصنف رحمه الله تعالى في هذا البيت علامات الاسم. فمنها الجر، وهو يشمل الجر بالحرف والإضافة والتبعية، نحو: مررت بغلام زيد الفاضل، فالغلام مجرور بالحرف، وزيد مجرور بالإضافة، والفاضل مجرور بالتبعية. وهو أشمل من قول غيره «بحرف الجر»، لأن هذا لا يتناول الجر بالإضافة ولا الجر بالتبعية.

ومنها التنوين، وهو على أربعة أقسام: تنوين التمكين، وهو اللاحق للأسماء المعربة كزيد ورجل. وتنوين التنكير، وهو اللاحق للأسماء المبنية فرقا بين معرفتها ونكرتها، نحو: مررت بسيبويه وبسيبويهٍ آخر. وتنوين المقابلة، وهو اللاحق لجمع المؤنث السالم، نحو: مسلمات، فإنه في مقابلة النون في جمع المذكر السالم كمسلمين. وتنوين العوض، وهو على ثلاثة أقسام: عوض عن جملة، وهو الذي يلحق «إذ» عوضا عن جملة تكون بعدها، كقوله تعالى: ﴿وَأَنتُمْ حِينَئِذٍ تَنظُرُونَ﴾، أي حين إذ بلغت الروح الحلقوم، فحذف «بلغت الروح الحلقوم» وأتى بالتنوين عوضا عنه.

:::callout{type="hashiya" span="side"}
**قوله ﴿وأنتم حينئذ تنظرون﴾:** من سورة الواقعة، الآية الرابعة والثمانون، وقبلها: ﴿فَلَوْلَا إِذَا بَلَغَتِ الْحُلْقُومَ﴾، فمنها قدّر الشارح الجملة المحذوفة.

**قوله «سيبويه»:** هو أبو بشر عمرو بن عثمان بن قنبر، إمام البصريين وصاحب الكتاب، توفي نحو سنة ثمانين ومئة.
:::

وقسم يكون عوضا عن اسم، وهو اللاحق لكل عوضا عما تضاف إليه، نحو: كلٌّ قائم، أي كل إنسان قائم، فحذف إنسان وأتى بالتنوين عوضا عنه. وقسم يكون عوضا عن حرف، وهو اللاحق لجوار وغواش ونحوهما رفعا وجرا، نحو: هؤلاء جوارٍ، ومررت بجوارٍ، فحذفت الياء وأتي بالتنوين عوضا عنها.

وتنوين الترنم، وهو الذي يلحق القوافي المطلقة بحرف علة، كقوله:

:::verse{style="matn"}
أقلّي اللوم عاذل والعتابن || وقولي إن أصبت لقد أصابن
:::

فجيء بالتنوين بدلا من الألف لأجل الترنم.

:::callout{type="hashiya" span="side"}
**قوله «كقوله»:** البيت لجرير من قصيدة يهجو بها الراعي النميري، والقافية فيه «والعتابا… أصابا»، فأبدل التنوين من ألف الإطلاق.
:::

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

واستعمل المصنف «أل» مكان الألف واللام، وقد وقع ذلك في عبارة بعض المتقدمين، وهو الخليل، واستعمل «مسند» مكان الإسناد له.

:::callout{type="hashiya" span="side"}
**قوله «وهو الخليل»:** الخليل بن أحمد الفراهيدي البصري، شيخ سيبويه وواضع علم العروض، توفي بالبصرة سنة سبعين ومئة، وقيل غير ذلك.
:::

:::verse{style="matn"}
بتا فعلت وأتت ويا افعلي || ونون أقبلن فعل ينجلي
:::

ثم ذكر المصنف أن الفعل يمتاز عن الاسم والحرف بتاء فعلت، والمراد بها تاء الفاعل، وهي المضمومة للمتكلم نحو: فعلتُ، والمفتوحة للمخاطب نحو: تباركتَ، والمكسورة للمخاطبة نحو: فعلتِ. ويمتاز أيضا بتاء أتت، والمراد بها تاء التأنيث الساكنة، نحو: نعمت وبئست، فاحترزنا بالساكنة عن اللاحقة للأسماء، فإنها تكون متحركة بحركة الإعراب، نحو: هذه مسلمةٌ، ورأيت مسلمةً، ومررت بمسلمةٍ.

ويمتاز أيضا بياء افعلي، والمراد بها ياء الفاعلة، وتلحق فعل الأمر نحو: اضربي، والفعل المضارع نحو: تضربين، ولا تلحق الماضي. ومما يميز الفعل نون أقبلن، والمراد بها نون التوكيد، خفيفة كانت أو ثقيلة، فالخفيفة نحو قوله تعالى: ﴿لَنَسْفَعًا بِالنَّاصِيَةِ﴾، والثقيلة نحو قوله تعالى: ﴿لَنُخْرِجَنَّكَ يَا شُعَيْبُ﴾. فمعنى البيت: ينجلي الفعل بتاء الفاعل وتاء التأنيث الساكنة وياء الفاعلة ونون التوكيد.

:::callout{type="hashiya" span="side"}
**قوله ﴿لنسفعا بالناصية﴾:** من سورة العلق، الآية الخامسة عشرة، وتُكتب النون الخفيفة فيها ألفا في المصحف.

**قوله ﴿لنخرجنك يا شعيب﴾:** من سورة الأعراف، الآية الثامنة والثمانين، من قول الملأ الذين استكبروا من قوم شعيب.
:::

:::paragraphs{style="note" dir=ltr}
**A note on the text.** Ibn ʿAqīl (d. 1367) on the opening of Ibn Mālik’s Alfiyya, from ar.wikisource, without the modern editor’s footnotes and two passages on the tanwīn of rhyme; punctuation added, a few typing slips corrected. The glosses in the margin are written for this page, each opening with the words it explains, as a Bulaq ḥāshiya does.
:::

:::paragraphs{style="colophon" dir=ltr}
Set in Amiri and Aref Ruqaa (SIL OFL) · Text: Ibn ʿAqīl and Ibn Mālik, public domain, from ar.wikisource · Glosses: Postext Cookbook
:::
`; // content.<lang>.md, inlined by the Cookbook

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { // every face the pages use, loaded before the build (gotcha: fonts-first)
  Amiri: ['400', '400i', '700'], // NASKH: text, matn, glosses; the Latin lines
  'Aref Ruqaa': ['700'], // RUQAA: the title page and the chapter title
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
// The arabic file of each face, which loadFonts leaves out (gotcha: arabic-fonts-subset).
await loadArabicFonts(FONTS, markdown);
const doc = await buildWithFonts(() => buildDocument({ markdown }, config()), markdown);
showBook(doc, { title: t({ en: 'A Bulaq page', es: 'Una página de Bulaq' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: arabicPdfProvider }), `${RECIPE}.pdf`);

// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ─────

// ─── Kit · core v1 ── the same in every recipe · postext.dev/cookbook ─────────
function mm(value) { return { value, unit: 'mm' }; }
function pt(value) { return { value, unit: 'pt' }; }
function em(value) { return { value, unit: 'em' }; }
/** The sample language's string: t({ en: 'Figure', es: 'Figura' }). */
function t(strings) { return strings[LANG] ?? Object.values(strings)[0]; }
/** A file in this recipe's assets folder, served from the Postext repo by jsDelivr. */
function asset(file) { return `https://cdn.jsdelivr.net/gh/drnachio/postext@main/cookbook/${RECIPE}/assets/${file}`; }

// ─── Kit · fonts v1 ── the same in every recipe · postext.dev/cookbook ────────
// Postext measures text with the faces the browser has loaded, and caches the
// widths, so every face must be ready before the first build. Faces come from
// Fontsource: the same static files the PDF embeds, so screen and PDF agree.

/** faces = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample:
 *  letters beyond Latin-1 (č, ł, ő…) also load the latin-ext files. With
 *  `optional`, a face Fontsource does not ship is skipped instead of failing.
 *  Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = {
    latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,'
      + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
    'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,'
      + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF',
  };
  const subsets = /[Ā-˿Ḁ-ỿ]/.test(text) ? ['latin', 'latin-ext'] : ['latin'];
  const jobs = [];
  let added = 0;
  for (const [family, specs] of Object.entries(faces)) {
    const id = fontsourceId(family);
    const meta = optional ? await fontsourceMeta(family) : null;
    for (const spec of new Set(specs)) {
      const weight = parseInt(spec, 10);
      const style = spec.endsWith('i') ? 'italic' : 'normal';
      if (hasFace(family, weight, style)) continue;
      if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue;
      for (const subset of subsets) {
        const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`;
        const face = new FontFace(family, `url(${url}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: ranges[subset] });
        jobs.push(face.load().then((ready) => { document.fonts.add(ready); added++; }, () => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return added;
}

/** Runs `build` (a buildDocument or buildBundle call) and checks the faces
 *  the pages use. A regular face missing from FONTS is loaded with a warning;
 *  bold and italic variants are loaded when the family ships them. Then the
 *  measurement caches are cleared and the build runs again. */
async function buildWithFonts(build, text = '') {
  const tried = new Set();
  for (let round = 0; round < 3; round++) {
    kitStatus('Laying out…');
    await new Promise(requestAnimationFrame);          // let the status paint first
    const result = await Promise.resolve().then(build).catch((error) => { kitFail(error); throw error; });
    const wanted = { base: {}, variants: {} };
    for (const { font, base } of [result].flat().flatMap(fontStringsOf)) {
      const { family, weight, style } = parseFont(font);
      const key = `${family}|${weight}|${style}`;
      if (tried.has(key) || hasFace(family, weight, style)) continue;
      tried.add(key);
      (wanted[base ? 'base' : 'variants'][family] ??= []).push(`${weight}${style === 'italic' ? 'i' : ''}`);
    }
    if (Object.keys(wanted.base).length) {
      console.warn(`[cookbook] FONTS does not list ${JSON.stringify(wanted.base)}: loading them.`);
    }
    const added = await loadFonts(wanted.base, text) + await loadFonts(wanted.variants, text, { optional: true });
    if (added === 0) return result;
    clearMeasurementCache();
  }
  throw new Error('The fonts did not settle after three builds.');
}

/** Every font string of the layout. `base` marks a block's own face; its
 *  bold, italic and bold-italic variants are listed whether or not used. */
function fontStringsOf(doc) {
  const found = new Map();
  const walk = (node) => {
    if (!node || typeof node !== 'object') return;
    if (Array.isArray(node)) { node.forEach(walk); return; }
    for (const [key, value] of Object.entries(node)) {
      if (typeof value === 'string' && /fontString$/i.test(key)) {
        found.set(value, found.get(value) || key === 'fontString');
      } else if (value && typeof value === 'object') walk(value);
    }
  };
  walk(doc.pages);
  walk(doc.blocks);
  return [...found].map(([font, base]) => ({ font, base }));
}

/** '700 37.5px Open Sans' / 'italic 400 13px "Source Serif 4"' → { family, weight, style }.
 *  A string with no weight ('95.8px Young Serif', from a design text) is 400. */
function parseFont(font) {
  const m = /^(?:(italic|oblique)\s+)?(?:small-caps\s+)?(?:(\d+|bold|normal)\s+)?[\d.]+px\s+(.+)$/.exec(font.trim());
  if (!m) throw new Error(`Unexpected font string: ${font}`);
  const weight = m[2] === 'bold' ? 700 : !m[2] || m[2] === 'normal' ? 400 : Number(m[2]);
  return { family: m[3].replace(/^["']|["']$/g, ''), weight, style: m[1] ? 'italic' : 'normal' };
}

/** True when a loaded FontFace covers exactly this family, weight and style
 *  (document.fonts.check() is also true for families nobody declared). */
function hasFace(family, weight, style) {
  for (const face of document.fonts) {
    if (face.status !== 'loaded' || face.style !== style) continue;
    if (face.family.replace(/^["']|["']$/g, '') !== family) continue;
    const [low, high = low] = face.weight.split(' ').map(Number);
    if (weight >= low && weight <= high) return true;
  }
  return false;
}

/** Fontsource's id for a family: 'Source Serif 4' → 'source-serif-4'. */
function fontsourceId(family) { return family.toLowerCase().replace(/\s+/g, '-'); }

/** The weights and styles a family ships ({ weights: [400, 700], styles: ['normal', 'italic'] }), or null. */
function fontsourceMeta(family) {
  fontsourceMeta.cache ??= new Map();
  const id = fontsourceId(family);
  if (!fontsourceMeta.cache.has(id)) {
    fontsourceMeta.cache.set(id, fetch(`https://api.fontsource.org/v1/fonts/${id}`)
      .then((res) => (res.ok ? res.json() : null), () => null));
  }
  return fontsourceMeta.cache.get(id);
}

// ─── Kit · viewer v1 ── the same in every recipe · postext.dev/cookbook ───────
/** Shows the pages as facing spreads on a dark desk: the first page is a
 *  recto on its own, then verso | recto pairs, as in a bound book. Pages
 *  are painted when they scroll near the screen. */
function showPages(docs, { title, width = 460 } = {}) {
  const root = viewer(title);
  const pages = [docs].flat().flatMap((doc) =>
    doc.pages.map((page) => ({ doc, page, n: (doc.pageIndexOffset ?? 0) + page.index })));
  const spreads = [];
  let verso = null;
  for (const p of pages) {
    if (p.n % 2 === 1) { if (verso) spreads.push([verso, null]); verso = p; }
    else { spreads.push([verso, p]); verso = null; }
  }
  if (verso) spreads.push([verso, null]);
  const density = Math.min(window.devicePixelRatio || 1, 2);
  showPages.painter?.disconnect();
  const painter = new IntersectionObserver((entries) => {
    for (const { isIntersecting, target } of entries) {
      if (!isIntersecting) continue;
      painter.unobserve(target);
      const { doc, page } = target.postext;
      renderPageToCanvas(page, doc, target, { scale: (width * density) / page.width });
    }
  }, { rootMargin: '800px' });
  showPages.painter = painter;
  root.replaceChildren(...spreads.map((pair) => {
    const spread = document.createElement('div');
    spread.className = 'pt-spread';
    for (const p of pair) {
      const figure = document.createElement('figure');
      if (p) {
        const label = p.page.pageLabel || String(p.n + 1);
        const canvas = document.createElement('canvas');
        canvas.postext = p;
        canvas.style.aspectRatio = `${p.page.width} / ${p.page.height}`;
        canvas.setAttribute('role', 'img');
        canvas.setAttribute('aria-label', `Page ${label}`);
        const folio = document.createElement('figcaption');
        folio.textContent = label;
        figure.append(canvas, folio);
        painter.observe(canvas);
      } else figure.className = 'pt-blank';
      spread.append(figure);
    }
    return spread;
  }));
  kitStatus(`${pages.length} ${pages.length === 1 ? 'page' : 'pages'}`);
  document.documentElement.dataset.postext = 'ready';
  return pages.length;
}

/** The desk, the bar and the error reporting, created once. */
function viewer(title) {
  if (!document.getElementById('pt-kit')) {
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit">
      :root { color-scheme: dark; }
      body { margin: 0; background: #0e1014; color: #b9bcc4; font: 13px/1.45 system-ui, sans-serif; }
      #pt-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center;
        gap: 6px 16px; padding: 10px 16px; background: rgb(14 16 20 / .92); backdrop-filter: blur(6px);
        border-bottom: 1px solid #23262d; }
      #pt-bar strong { color: #f4f1ea; font-weight: 600; }
      #pt-actions { display: flex; gap: 12px; margin-left: auto; }
      #pt-actions a, #pt-actions button { color: #d8a21a; font: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
      #pages { display: grid; justify-items: center; gap: 48px; padding: 32px 16px 72px; }
      .pt-spread { display: flex; }
      .pt-spread figure { margin: 0; width: min(460px, 44vw); }
      .pt-spread canvas { display: block; width: 100%; background: #fff;
        box-shadow: 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figure:first-child canvas { box-shadow: inset -14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figcaption { margin-top: 10px; text-align: center; font: 600 10px/1 system-ui, sans-serif;
        letter-spacing: .18em; text-transform: uppercase; color: #6c7079; }
      .pt-blank { visibility: hidden; }
      @media (max-width: 760px) {
        .pt-spread { flex-direction: column; gap: 32px; }
        .pt-spread figure { width: min(460px, 92vw); }
        .pt-blank { display: none; }
      }
    </style>`);
    document.body.insertAdjacentHTML('afterbegin',
      '<header id="pt-bar"><strong id="pt-title"></strong><span id="pt-status" role="status"></span><span id="pt-actions"></span></header>');
    document.getElementById('pt-title').textContent = document.title || 'Postext';
    addEventListener('error', (event) => kitFail(event.error ?? event.message));
    addEventListener('unhandledrejection', (event) => kitFail(event.reason));
  }
  if (title) document.getElementById('pt-title').textContent = title;
  return document.getElementById('pages')
    ?? document.body.appendChild(Object.assign(document.createElement('main'), { id: 'pages' }));
}

function kitStatus(text) {
  viewer();
  document.getElementById('pt-status').textContent = text;
}

function kitFail(error) {
  document.documentElement.dataset.postext = 'error';
  kitStatus(`Error: ${error?.message ?? error}`);
}

// ─── Kit · pdf v1 ── the same in every recipe that exports a PDF ──────────────
/** postext-pdf embeds TrueType bytes. Fetch the Fontsource file the screen
 *  used, snapping to a weight the family ships and falling back to upright
 *  when it has no italic: the PDF asks for every face a block could use. */
async function fontsourceProvider(family, weight, style) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  const weights = meta?.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && meta && !meta.styles.includes('italic') ? 'normal' : style;
  const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`);
  if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} (${res.status})`);
  return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
}

/** A "Build the PDF" button in the bar. Once built: "Open the PDF" (a new
 *  tab, since CodePen's preview frame cannot show PDFs) and a download link. */
function offerPdf(makePdf, filename) {
  viewer();
  const button = Object.assign(document.createElement('button'), { type: 'button', textContent: 'Build the PDF' });
  button.dataset.postextPdf = filename;
  button.addEventListener('click', async () => {
    button.disabled = true;
    button.textContent = 'Building the PDF…';
    try {
      const bytes = await makePdf();
      const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' }));
      const size = `${Math.max(1, Math.round(bytes.length / 1024))} KB`;
      button.replaceWith(
        Object.assign(document.createElement('a'), { href: url, target: '_blank', rel: 'noopener', textContent: 'Open the PDF ↗' }),
        Object.assign(document.createElement('a'), { href: url, download: filename, textContent: `Download ${filename} · ${size}` }));
    } catch (error) {
      button.disabled = false;
      button.textContent = 'Build the PDF';
      kitFail(error);
    }
  });
  document.getElementById('pt-actions').append(button);
}

// ─── Kit · arabic v1 ── Arabic-script faces · postext.dev/cookbook ───────────
// Fontsource ships an Arabic family as one file per subset and weight: the
// `arabic` file holds the letters, the harakat, the Arabic-Indic digits, the
// Arabic punctuation and the presentation forms; `latin` and `latin-ext`
// hold the rest. loadFonts loads the latin files; this block adds the arabic
// file of every Arabic family, for the canvas and for the PDF, which shapes
// the letters with HarfBuzz from the same bytes.

/** The code points of Fontsource's `arabic` subset, as its stylesheets
 *  declare them (the same unicode-range the browser picks the file by). A
 *  function, not a const: the kit is inlined after the recipe's top-level
 *  awaits, and a const read before its line throws, where a function
 *  declaration is hoisted. */
function arabicRange() {
  return 'U+0600-06FF,U+0750-077F,U+0870-088E,U+0890-0891,U+0897-08E1,U+08E3-08FF,'
    + 'U+200C-200E,U+2010-2011,U+204F,U+2E41,U+FB50-FDFF,U+FE70-FE74,U+FE76-FEFC,U+102E0-102FB,'
    + 'U+10E60-10E7E,U+10EC2-10EC4,U+10EFC-10EFF,U+1EE00-1EEFF';
}

/** Whether code point `cp` is in the arabic file. */
function inArabicRange(cp) {
  inArabicRange.ranges ??= arabicRange().split(',').map((part) => {
    const [lo, hi = lo] = part.slice(2).split('-');
    return [parseInt(lo, 16), parseInt(hi, 16)];
  });
  return inArabicRange.ranges.some(([lo, hi]) => cp >= lo && cp <= hi);
}

/** Whether Fontsource serves `family` with an `arabic` subset. Fails when
 *  the API does not answer: an Arabic face taken for a Latin one would set
 *  its letters in a system face. */
async function isArabicFamily(family) {
  const meta = await fontsourceMeta(family);
  if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`);
  return !!meta.subsets?.includes('arabic');
}

/** The arabic file of a face. */
function arabicFileUrl(family, weight, style) {
  const id = fontsourceId(family);
  return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-arabic-${weight}-${style}.woff2`;
}

/** faces = { Amiri: ['400', '700'] }, as for loadFonts, after it: the whole
 *  FONTS object may be passed, its families without an arabic subset are
 *  left alone. Adds the arabic file of every listed weight of each Arabic
 *  family (the latin files come from loadFonts) and loads it. `text` is
 *  the sample: fails when it holds an Arabic-script character the arabic
 *  file does not cover. List every weight the pages set in Arabic: a weight
 *  left to buildWithFonts gets the latin file only, and its Arabic letters
 *  fall back to a system face. Resolves to the number of files loaded. */
async function loadArabicFonts(faces, text = '') {
  kitStatus('Loading fonts…');
  let loaded = 0;
  try {
    const outside = [...new Set(text)].filter((ch) => /\p{Script=Arabic}/u.test(ch) && !inArabicRange(ch.codePointAt(0)));
    if (outside.length) throw new Error(`Fontsource's arabic files have no ${outside.slice(0, 12).join(' ')}`);
    for (const [family, specs] of Object.entries(faces)) {
      if (!(await isArabicFamily(family))) continue;
      for (const spec of new Set(specs)) {
        const weight = parseInt(spec, 10);
        const style = spec.endsWith('i') ? 'italic' : 'normal';
        const face = new FontFace(family, `url(${arabicFileUrl(family, weight, style)}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: arabicRange() });
        document.fonts.add(await face.load().catch(() => {
          throw new Error(`Fontsource has no arabic file for ${family} ${weight} ${style}`);
        }));
        loaded++;
      }
    }
  } catch (error) {
    kitFail(error);
    throw error;
  }
  return loaded;
}

/** The PDF font provider for recipes with Arabic faces: a family with an
 *  arabic subset gets its arabic file when its pages set Arabic letters
 *  (`request.codePoints`), then its latin file, and its latin-ext file for
 *  the letters beyond latin (transliteration: ā ḥ ʿ). The arabic file comes
 *  first: it also holds the space and the brackets, so a line of Arabic is
 *  shaped as one run and not cut at every space. Any other family goes to
 *  fontsourceProvider (the "pdf" block). */
async function arabicPdfProvider(family, weight, style, request) {
  if (!(await isArabicFamily(family))) return fontsourceProvider(family, weight, style);
  const meta = await fontsourceMeta(family);
  const weights = meta.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style;
  const wanted = [...(request?.codePoints ?? [])];
  const id = fontsourceId(family);
  const urls = [];
  if (!wanted.length || wanted.some(inArabicRange)) urls.push(arabicFileUrl(family, w, s));
  urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`);
  if (meta.subsets.includes('latin-ext') && wanted.some((cp) => /[Ā-˿Ḁ-ỿ]/u.test(String.fromCodePoint(cp)))) {
    urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-ext-${w}-${s}.woff2`);
  }
  return Promise.all(urls.map(async (url) => {
    const res = await fetch(url);
    if (!res.ok) throw new Error(`Fontsource file ${url} (${res.status})`);
    return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
  }));
}

// ─── Kit · book v1 ── books bound on either edge · postext.dev/cookbook ──────
// A book bound on the right (Arabic, Hebrew or Persian text, vertical
// Chinese, or page.binding 'right') opens from what a Latin reader calls
// the back: page 1 lies alone on the left of the spine, then [3 | 2].

/** showPages for a book bound on either edge. A right-bound book (the
 *  document says so: doc.binding is 'right' for page.binding 'right', for
 *  text that runs right to left and for vertical text, when the binding is
 *  left to 'auto') lies on the desk as it opens: page 1 alone on the left
 *  of the spine, then [3 | 2], the spine shade on each page's inner edge.
 *  `binding` ('left' | 'right') overrides the document's. */
function showBook(docs, { binding, ...options } = {}) {
  const count = showPages(docs, options);
  const right = (binding ?? [docs].flat()[0]?.binding) === 'right';
  if (!document.getElementById('pt-kit-book')) {
    // The pages keep direction ltr, as in a left-bound book: a canvas takes
    // the direction its element inherits, and under the spread's rtl a run
    // painted for an ltr canvas would end where the engine starts it.
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit-book">
      .pt-spread[dir="rtl"] canvas { direction: ltr; }
      .pt-spread[dir="rtl"] figure:first-child canvas { box-shadow: inset 14px 0 14px -14px rgb(0 0 0 / .18),
        0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
    </style>`);
  }
  // Each pair stays [verso, recto] in the page; right to left, the verso
  // sits on the right. Phones stack the pages in reading order either way.
  for (const spread of document.querySelectorAll('#pages > .pt-spread')) spread.dir = right ? 'rtl' : 'ltr';
  document.getElementById('pages').dataset.binding = right ? 'right' : 'left';
  return count;
}

// ─── /Kit ───────────────────────────────────────────────────────────────────────
```

## تنويعات

### ضع الشرح في الجانب الداخلي

بعض المطابع تنضّد الحاشية عند الكعب، فيحتفظ المتن بالهامش الخارجي الأعرض.

```diff
-const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
+const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'inner',
```

### أحِط كل حاشية بإطار

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

```diff
-  stripe: { enabled: false }, border: { enabled: false },
+  stripe: { enabled: false }, border: { enabled: true, width: pt(0.4), color: col('rule') },
```

## أخطاء شائعة

- **اوسم الكتاب العربي بـ 'ar'، لا بـ LANG.** نسختا الوصفة هما en وes، لكن المثال العربي عربي في كلتيهما: `locale: LANG` سيجعله من اليسار إلى اليمين، ويجلّده على اليسار، ويرقّم صفحاته 1 2 3، ويسمّي أشكاله Figure أو Figura. اكتب الوسم بنفسك: 'ar' (الأرقام العربية المشرقية، عُرف المشرق)، أو منطقة مثل 'ar-EG' أو 'ar-SA'، أو 'ar-MA' أو 'ar-DZ' أو 'ar-TN' لنسخة مغاربية بالأرقام الأوروبية. أما الصفحة اللاتينية التي تقتبس العربية فقط فتحتفظ بلغتها.
- **الخطوط العربية تحتاج إلى ملفها arabic، عبر الكتلة arabic.** يقدّم Fontsource الخطوط Amiri وNoto Naskh Arabic وScheherazade New في ملف لكل مجموعة فرعية، والحروف العربية في ملف arabic. لا يجلب loadFonts إلا latin (وlatin-ext)، فيأتي النص العربي على الشاشة من خط النظام ويُقاس خطأً، ويسلّم fontsourceProvider ملف latin ذاك إلى PDF، فيطبع مربعات فارغة. اذكر كتلة الأدوات arabic، واستدعِ loadArabicFonts(FONTS, markdown) بعد loadFonts، مع ذكر كل وزن تضع به الصفحاتُ نصًا عربيًا في FONTS، وأعطِ renderToPdf القيمة fontProvider: arabicPdfProvider.
- **أي كائن headings يُلغي فاصل الصفحة قبل H1.** ينتقل H1 افتراضيًا إلى صفحة فردية (always-odd)، لكن تمرير أي كائن headings يعيد ضبط هذا الافتراض، فتتوالى الفصول دون فاصل ولا يفعل span: 'page' شيئًا. أعد كتابة headings.levels[0].breakBefore: { enabled: true, parity } في كل إعداد.
- **حمّل كل أوجه الخط قبل الإخراج.** يقيس الإخراج النص بأوجه الخط التي حمّلها المتصفح ويخزّن العروض مؤقتًا، فالوجه الذي يصل بعد البناء الأول يترك فواصل أسطر خاطئة وملف PDF لم يعد يطابق الشاشة. حمّل كل وزن وكل نمط أولًا، واستدعِ clearMeasurementCache() قبل إعادة البناء إذا تأخر وصول أحدها.

## الحقوق

- الوصفة: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- النص: Ibn ʿAqīl’s commentary on the opening of the Alfiyya, with Ibn Mālik’s verses, as ar.wikisource gives it (revision 521625), without the modern editor’s footnotes: Ibn ʿAqīl, Ibn Mālik ([المصدر](https://ar.wikisource.org/wiki/شرح_ابن_عقيل/المجلد_الأول/الكلام_وما_يتألف_منه)), ملكية عامة
- النص: The glosses in the margin, the title page, the note on the text and the colophon: Postext Cookbook, أصلي
- الخطوط: Amiri (OFL-1.1), Aref Ruqaa (OFL-1.1)
- الشيفرة: MIT · محتوى المثال: MIT

## وصفات ذات صلة

- [رقم 110 · قصيدة في صفحة ديوان، كل بيت في شطرين](https://postext.dev/ar/cookbook/qasida-diwan-page.md): كتلة :::verse واحدة تنضّد أبيات المتنبي الستة والأربعين في عمودين من الأشطر، ويُمدّ كل شطر بالكشيدة إلى عرض واحد. · المستوى 2 (متوسط) · الشعر
- [رقم 001 · كتاب مدرسي بعمود في الهامش](https://postext.dev/ar/cookbook/textbook-margin-column.md): صفحة بعمود ونصف لا يحمل عمودها الخارجي إلا العناصر العائمة: تتراكم فيه الأشكال ذات span 'side' والحواشي الشارحة، وينقل captionSide إليه بقية التعليقات. · المستوى 3 (متقدم) · الكتب المدرسية
- [رقم 032 · طبعة كلاسيكية محشّاة بتعليقات في الهامش](https://postext.dev/ar/cookbook/annotated-classic-glosses.md): حفلة الشاي المجنونة من «أليس» في طبعة محشّاة: تعليقات خضراء وحمراء في الهامش الخارجي بجوار الأسطر التي تشرحها، يستدعي كلًّا منها حرف بلونها. · المستوى 3 (متقدم) · الأدب القصصي والمسرح والنثر الأدبي