Skip to main content
Recipe number 112

Cookbook · Chapter 3 · Headings & openers

Tale headings in Arabic ordinal words: the first night…

A level template writes each night as الليلة and a feminine ordinal, الليلة الأولى, الثانية, الثالثة, so the Markdown never carries a number.

On this page
Output
Canvas · PDF
Postext
Tested with Postext 1.65.0
Needs ≥ 1.25.0 · postext-pdf ≥ 1.25.0
Licence
Updated 10 Oct 2026
Code MIT · Text MIT

pp. ٢–٣ · 2–3 of 10

  • Trim 170 × 240 mm
  • 1 column
  • Amiri 13/26
  • Aref Ruqaa
  • Noto Kufi Arabic
  • 10 pages
  • Level
  • Postext 1.65.0
  • Laid out in 129 ms
  • 158 lines of code

In short

The opening of the Thousand and One Nights, where each night is headed with its number written out in Arabic words, “the first night”, “the second night”, in the feminine form that goes with the Arabic word for night.

What you'll build

Ten pages from the beginning of the Thousand and One Nights: a half-title, then the Merchant and the Jinni, the first tale Shahrazad tells, which runs over three nights. Each night opens with Hindawi’s formula فلما كانت in small Kufi over its number in green Ruqʿa, الليلة الأولى, الليلة الثانية, الليلة الثالثة, written out as the books print it. None of those numbers is in the Markdown: the heading level counts the nights and writes each count as a feminine ordinal, which agrees with ليلة. The tale opens under a gold-ruled headpiece, the three old men’s stories have their own small titles, and the running heads carry the book and the tale. The text is the Hindawi Foundation’s 2022 edition, under CC BY 4.0.

This recipe answers

  • How do I number chapters in Arabic ordinal words, such as الليلة الأولى?

The short answer

script.js · lines 34–54in full code
// In the Markdown a night is a level-2 heading with no number: ## الليلة
// The level's template writes الليلة and the counter as a feminine ordinal, which agrees
// with the noun: الليلة الأولى، الليلة الثانية، الليلة الثالثة … الليلة الحادية بعد الألف.
// numberPosition 'replace' makes that number the whole title, so the heading, the PDF
// bookmarks and the alt text read الليلة الثانية. Hindawi's formula is a fixed design text.
const nights = {
  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine}', numberPosition: 'replace',
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 2),
  advancedDesign: { enabled: true, minHeight: mm(18), slot: { elements: [
    { kind: 'text', id: 'formula', content: 'فلما كانت', fontFamily: KUFI, fontWeight: 500,
      fontSize: pt(8), align: 'center', color: col('muted'), placement: top(0) },
    { kind: 'text', id: 'night', content: '{titleText}', fontFamily: RUQAA, fontWeight: 700,
      fontSize: pt(21), lineHeight: 1.2, align: 'center', color: col('accent'),
      placement: top(4.5) },
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...top(16), size: { width: mm(16) } } },
  ] } },
};
// A tale does not count: an unnumbered heading leaves the deeper counters alone, so the
// nights run on from one tale to the next instead of starting again at الأولى.
const tale = { numbered: false, runningChapter: true };

The night's number in feminine ordinal words, from a level template

Ingredients

Type
Amiri, Aref Ruqaa, Noto Kufi Arabic (SIL OFL 1.1)
Assets
None: every picture is drawn in code

Method

#1 · Nights counted in words

The code is the short answer above. A night is a level-2 heading, ## الليلة, and the level’s numberingTemplate is 'الليلة {2:ordinal-feminine}': the -feminine modifier writes الأولى, الثانية, الحادية عشرة, الحادية بعد الألف (Ordinal and cardinal words, Spelled-out numbers). With numberPosition: 'replace' the number is the heading’s whole title: whatever the Markdown says after ## is dropped, and the heading, the PDF bookmarks and the alt text read الليلة الثانية. The design prints that title, {titleText}, large, and Hindawi’s formula فلما كانت, a fixed text, small above it. The tale headings use a style with numbered: false: a numbered level 1 would restart the night count with every tale, while an unnumbered one leaves the deeper counters alone, so the nights run on through the book.

Page 5: the second night, its number written out by the template and printed as the whole heading.

#2 · A headpiece for each tale

script.js · lines 58–75in full code
const rule = (id, y, thickness) => ({ kind: 'rule', id, direction: 'horizontal',
  thickness: pt(thickness), color: col('gold'),
  placement: { ...top(y), size: { width: 'fill' } } });
const opener = {
  enabled: true, minHeight: mm(50),
  slot: { elements: [
    { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
      placement: { ...top(4), size: { width: 'fill', height: mm(30) } } },
    rule('band-top', 4, 1.2), rule('band-foot', 34, 0.5),
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', fontFamily: KUFI, fontWeight: 500,
      fontSize: pt(8.5), align: 'center', color: col('muted'), placement: top(7.5) },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: RUQAA, fontWeight: 700,
      fontSize: pt(30), lineHeight: 1.15, align: 'center', color: col('accent'),
      placement: top(13) },
    { kind: 'text', id: 'latin', content: '{attr.latin}', fontFamily: NASKH, italic: true,
      fontSize: pt(9.5), align: 'center', color: col('muted'), placement: top(39) },
  ] },
};

The level-1 heading is a band of tint between two gold rules, the tale’s title in Ruqʿa over it, a kicker and a Latin line from heading attributes, {kicker="…" latin="…"}. The Latin line is the only part of the opener that changes with the edition.

#3 · Running heads that come with the tale

script.js · lines 79–93in full code
// Running heads stay on the sheet's sides: in a book bound on the right the verso (even)
// is the right-hand page, so its outer edge, where the folio goes, is the right one.
const head = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: KUFI, fontWeight: 500, fontSize: pt(8.5),
  color: col('muted'), placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(12) } },
  ...extra });
const taleHeads = { elements: [
  head('verso-folio', '{pageNumber}', 'even', 'top-right', -OUTER, { color: col('accent') }),
  head('verso-book', '{title}', 'even', 'top-right', -(OUTER + 10)),
  head('recto-tale', '{chapterTitle}', 'odd', 'top-left', OUTER + 10),
  head('recto-folio', '{pageNumber}', 'odd', 'top-left', OUTER, { color: col('accent') }),
] };
const footer = { elements: [head('drop-folio', '{pageNumber}', 'all', 'bottom', 0, {
  pages: 'opener', color: col('accent'),
  placement: { anchor: { to: 'page', edge: 'bottom' }, offset: { y: mm(-12) } } })] };

The running heads belong to the tale heading style, so each tale brings its own; the half-title has none. The verso carries the book’s title and the recto {chapterTitle}, the tale. In a book bound on the right the verso is the right-hand page, so its folio goes to the top right (Page order and right binding).

#4 · A half-title in Ruqʿa

script.js · lines 97–115in full code
const at = (y) => ({ anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) } });
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'), placement: at(y), ...style });
const titlePage = {
  id: 'title', span: 'page', numbered: false, runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] }, footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'rule', id: 'over', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...at(62), size: { width: mm(40) } } },
    line('book', '{titleText}', 70, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(54),
      lineHeight: 1.25, color: col('accent') }),
    { kind: 'rule', id: 'under', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...at(100), size: { width: mm(40) } } },
    line('volume', '{attr.kicker}', 106, { fontFamily: KUFI, fontWeight: 500, fontSize: pt(11),
      color: col('accent') }),
    line('latin', '{attr.latin}', 150, { fontFamily: NASKH, fontSize: pt(9.5), italic: true,
      color: col('muted') }),
  ] } },
};

The half-title is a heading style with span: 'page', numbered: false and empty header and footer, so it neither counts nor carries a running head.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 112 · Night headings in Arabic ordinal words ═══════════
// https://postext.dev/en/cookbook/nights-ordinal-headings
// Code: MIT · Text: Alf layla wa-layla, Hindawi Foundation 2022 (CC BY 4.0) · Pictures: none
// Fonts: Amiri, Aref Ruqaa, Noto Kufi Arabic (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import { buildDocument, withLoadedFonts, renderPageToCanvas } 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 = 'nights-ordinal-headings';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Black text, a deep green for the titles and a gold hairline, on a cream paper.
const palette = {
  ink: '#1c1a17', // text: a warm near-black
  accent: '#1f564c', // titles, night headings, folios
  gold: '#a8833a', // the rules under the nights and around the headpiece
  tint: '#ebe3cc', // the headpiece band
  muted: '#5e594f', // running heads, kickers, the note on the text
  paper: '#faf6ec', // a cream 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: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
const NASKH = 'Amiri'; // the text and the sub-tale titles
const RUQAA = 'Aref Ruqaa'; // display: the book, the tale, the nights
const KUFI = 'Noto Kufi Arabic'; // labels: kickers, running heads, folios
const [SIZE, LEAD] = [13, 26]; // pt: 2 × the size: a ḍamma over a hamza clears the line above
const [OUTER, TOP] = [18, 22]; // mm: a 17 × 24 cm book
const top = (y) => ({ anchor: { to: 'container', edge: 'top' }, offset: { y: mm(y) } });

// #region answer: the night's number in feminine ordinal words, from a level template
// In the Markdown a night is a level-2 heading with no number: ## الليلة
// The level's template writes الليلة and the counter as a feminine ordinal, which agrees
// with the noun: الليلة الأولى، الليلة الثانية، الليلة الثالثة … الليلة الحادية بعد الألف.
// numberPosition 'replace' makes that number the whole title, so the heading, the PDF
// bookmarks and the alt text read الليلة الثانية. Hindawi's formula is a fixed design text.
const nights = {
  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine}', numberPosition: 'replace',
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 2),
  advancedDesign: { enabled: true, minHeight: mm(18), slot: { elements: [
    { kind: 'text', id: 'formula', content: 'فلما كانت', fontFamily: KUFI, fontWeight: 500,
      fontSize: pt(8), align: 'center', color: col('muted'), placement: top(0) },
    { kind: 'text', id: 'night', content: '{titleText}', fontFamily: RUQAA, fontWeight: 700,
      fontSize: pt(21), lineHeight: 1.2, align: 'center', color: col('accent'),
      placement: top(4.5) },
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)

Variations

#Start at the thousand and first night

{startAt=1001} on a night heading sets its counter, and the template writes الليلة الحادية بعد الألف (Heading attributes).

-## الليلة
+## الليلة {startAt=1001}

#Spell the hundreds the Bulaq way

-classical writes مائة for مئة, so the two hundredth night reads الليلة المائتان.

-  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine}', numberPosition: 'replace',
+  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine-classical}', numberPosition: 'replace',

#Number chapters in the masculine

Without a modifier the ordinal is masculine, for a noun such as الفصل: الفصل الأول، الفصل الثاني.

-  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine}', numberPosition: 'replace',
+  level: 2, numberingTemplate: 'الفصل {2:ordinal}', numberPosition: 'replace',

Pitfalls

Pitfall

Tag an Arabic book 'ar', not with LANG

A recipe's editions are en and es, but an Arabic sample is Arabic in both: `locale: LANG` would set it left to right, bind it on the left, number its pages 1 2 3 and caption its figures Figure or Figura. From postext 1.30 the tag is also the language the text is shaped in (measured, painted and embedded), so under an English or Spanish tag a face such as Markazi Text does not draw the Arabic forms of its guillemets and stops, and the lines break elsewhere. Write the tag yourself: 'ar' (Arabic-Indic digits, the Mashriq convention), a region such as 'ar-EG' or 'ar-SA', or 'ar-MA', 'ar-DZ' or 'ar-TN' for a Maghreb edition with European digits. A Latin page that only quotes Arabic keeps its own locale. Right-to-left text →

Pitfall

Arabic faces need their arabic file, through the arabic block

Fontsource serves Amiri, Noto Naskh Arabic or Scheherazade New as one file per subset, and the Arabic letters are in the arabic file. loadFonts fetches only latin (and latin-ext), so on screen the Arabic comes from a system face and measures wrong, and fontsourceProvider hands the PDF that latin file, which prints empty boxes. List the arabic kit block, call loadArabicFonts(FONTS, markdown) after loadFonts, with every weight the pages set in Arabic listed in FONTS, and give renderToPdf fontProvider: arabicPdfProvider. Arabic fonts →

Credits

Text
  • The Merchant and the Jinni, nights 1 to 3 of Alf layla wa-layla, from the Hindawi Foundation edition (2022, vol. 1), with its vowels and punctuation · Hindawi Foundation · CC BY 4.0
  • The kickers in Arabic, the note on the text and the colophon · Postext Cookbook · original
Fonts
Amiri (SIL OFL 1.1) · Aref Ruqaa (SIL OFL 1.1) · Noto Kufi Arabic (SIL OFL 1.1)
SandboxPDF