In short
An old Arabic story printed with all its small vowel signs above and below the letters. The lines are spaced wide enough that the signs of one line do not run into the line below.
What you'll build
Four pages of a classical Arabic book in which every letter carries its vowel: al-Hamadhānī’s Maqāma of the Madhouse, in which a madman in the asylum of Basra routs a theologian and then names himself in verse. Fully vocalised text stacks fatḥa and shadda over the letters and kasra under them, and the marks live in the space between lines. So the page is set in Amiri at 14 pt on 28 pt, twice the size, and nothing else: the leading is the design. The text is justified with kashidas, opens with a 1.5 em indent on the right, and sets its three Qurʾān quotations between the ornate brackets ﴿ ﴾ of the printed muṣḥaf. Only the Latin title line and the note on the text change with the edition.
This recipe answers
- How much leading does fully vocalised Arabic need?
The short answer
// Every letter of this maqāma carries its vowel: fatḥa and shadda over the letters, kasra
// and kasratān under them, often two marks on one letter. The marks sit in the leading,
// which never grows for them, so the leading is chosen for the most vocalised line of the
// book. Unvocalised prose sets well at 1.6 × the size; fully vocalised text needs
// 1.9–2.1 ×: here 14 pt on 28 pt, 2 ×, so a kasra hanging under one line clears a shadda
// standing on the line below. Any closer and the build reports the paragraph
// (arabicMarksExceedLeading) with the leading it would need.
const SIZE = 14; // pt
const LEAD = 2 * SIZE; // pt: 28
const bodyText = {
fontFamily: NASKH, fontSize: pt(SIZE), lineHeight: pt(LEAD), color: col('ink'),
boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
// Justified with kashidas, the default in an Arabic book, written out to say so:
// a line widens at its joins as well as at its spaces.
textAlign: 'justify', kashida: 'auto', kashidaPatterns: 'naskh',
firstLineIndent: em(1.5), indentAfterHeading: false, // on the start side, the right
optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true,
};
A leading of 2 × the size for text with every vowel written
Ingredients
- Features
- Arabic fontsBody typeRight-to-left textArabic as the document languageIndents, alignment and paragraph spacingKashida justificationArabic verse (bayt in two hemistichs)Books bound on the rightParagraphs in the other directionHeading levelsTrim sizeMirrored marginsPaper colourSemantic colour palettePages on a canvas
- Type
- Amiri, Aref Ruqaa (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · A leading of twice the size
The code is the short answer above. Leading never grows to make room for the marks: a kasra under one line and a shadda on top of the next share the same gap, so the gap is chosen for the most vocalised line of the book (Vowel marks). On this text, a leading of 1.6 × the size leaves six paragraphs whose marks collide and 1.9 × still leaves one; at 2 × none do. The build tells you: when two lines collide it reports arabicMarksExceedLeading for the paragraph, with the leading it would need (Arabic text).

#2 · A small page with a wide measure
// 166 mm of text block hold seventeen lines on the 28 pt pitch (9.88 mm). The measure is
// 106 mm, about twelve words of vocalised Naskh.
const page = {
sizePreset: 'custom', width: mm(140), height: mm(210), dpi: 150,
backgroundColor: col('paper'),
// mirror: left is the inner margin, at the spine (the right edge of an odd page here)
margins: { top: mm(22), bottom: mm(22), left: mm(18), right: mm(16), mirror: true },
};
A 14 × 21 cm page with 16 and 18 mm side margins leaves a 106 mm measure, about twelve vocalised words, and seventeen lines on the 28 pt pitch. The marks make the lines look grey, so the page stays plain: no running heads, a cream paper, one red title. mirror: true puts the wider margin at the spine, which in a book bound on the right is the right edge of an odd page (Page order and right binding).
#3 · Titles that keep the grid
// The headings carry no design: the title's line box, three lines of the grid deep, lowers
// it on the page (a top margin is dropped at the head of a page), and the levels under it
// keep to the 28 pt pitch, so the text starts on a line of the grid.
const headings = {
fontFamily: NASKH, color: col('ink'), textAlign: 'center',
levels: [
// The maqāma opens on a recto.
{ level: 1, fontFamily: RUQAA, fontWeight: 700, fontSize: pt(32), lineHeight: pt(LEAD * 3),
color: col('rubric'), marginTop: pt(0), marginBottom: pt(0),
breakBefore: { enabled: true, parity: 'odd' } },
{ level: 2, fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD), color: col('ink'),
marginTop: pt(0), marginBottom: pt(0) },
{ level: 3, fontWeight: 400, fontSize: pt(10), lineHeight: pt(LEAD), color: col('muted'),
marginTop: pt(0), marginBottom: pt(LEAD) },
],
};
The headings have no design: the Ruqʿa title sits in a line box three lines of the grid deep, and the author and the Latin line each take one line of 28 pt, so the first line of text falls on the grid. The Latin line is {dir=ltr}, a left-to-right heading in a right-to-left book (Document, block and inline direction).
The whole recipe
// ═══ Postext Cookbook · Nº 111 · Fully vocalised classical prose with Qur'anic brackets ═══
// https://postext.dev/en/cookbook/vocalised-classical-prose
// Code: MIT · Text: al-Hamadhānī, Maqāmāt, ar.wikisource (PD) · Pictures: none
// Fonts: Amiri, Aref Ruqaa (SIL OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocument, withLoadedFonts, renderPageToCanvas } from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'vocalised-classical-prose';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Black text and a red title on a cream page, as the Beirut and Cairo editions of the
// Maqāmāt print them.
const palette = {
ink: '#211b17', // text: a warm near-black
rubric: '#94291d', // the accent: the title
muted: '#6b6156', // the author's name, the Latin title line, the note on the text
paper: '#fbf7ee', // 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: 'rubric (defaults)', value: { hex: palette.rubric, model: 'hex' } },
];
const NASKH = 'Amiri'; // the text: a Bulaq Naskh, with its own Latin for the note
const RUQAA = 'Aref Ruqaa'; // display: the title
// #region answer: a leading of 2 × the size for text with every vowel written
// Every letter of this maqāma carries its vowel: fatḥa and shadda over the letters, kasra
// and kasratān under them, often two marks on one letter. The marks sit in the leading,
// which never grows for them, so the leading is chosen for the most vocalised line of the
// book. Unvocalised prose sets well at 1.6 × the size; fully vocalised text needs
// 1.9–2.1 ×: here 14 pt on 28 pt, 2 ×, so a kasra hanging under one line clears a shadda
// standing on the line below. Any closer and the build reports the paragraph
// (arabicMarksExceedLeading) with the leading it would need.
const SIZE = 14; // pt
const LEAD = 2 * SIZE; // pt: 28
const bodyText = {
fontFamily: NASKH, fontSize: pt(SIZE), lineHeight: pt(LEAD), color: col('ink'),
boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
// Justified with kashidas, the default in an Arabic book, written out to say so:
// a line widens at its joins as well as at its spaces.
textAlign: 'justify', kashida: 'auto', kashidaPatterns: 'naskh',
firstLineIndent: em(1.5), indentAfterHeading: false, // on the start side, the right
optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true,
};
// #endregion
// #region page: a 14 × 21 cm book page, seventeen lines of 28 pt
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
#Strip the vowels for a reading edition
tashkil: 'strip' removes the short vowels and the shadda from the layout, so the same text can be set at 1.6 × the size; 'strip-vowels' keeps the shadda.
- textAlign: 'justify', kashida: 'auto', kashidaPatterns: 'naskh',
+ textAlign: 'justify', kashida: 'auto', kashidaPatterns: 'naskh', tashkil: 'strip',#See the warning
Set the leading to 1.6 × the size and the build reports six paragraphs with arabicMarksExceedLeading, each with the leading it needs, up to 1.89 em on this text.
-const LEAD = 2 * SIZE; // pt: 28
+const LEAD = 1.6 * SIZE; // pt: 22.4Pitfalls
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 →
Layout warning · arabicMarksExceedLeading
Vowel marks crowd the next line
Why. A paragraph of vocalised Arabic sets its vowel marks (fatḥa, kasra, shadda, tanwīn…) in the leading, which never grows for them: where a mark over a word of one line reaches the letters or marks hanging under the word above it, the two lines touch.
Fix. Raise `bodyText.lineHeight` (1.7–1.85 em for partly vocalised text, 1.9–2.1 em for fully vocalised verse), give the paragraph a paragraph style with more leading, or set `bodyText.tashkil: 'strip-vowels'` for an edition without vowels. Docs →
Credits
- Recipe
- Ignacio Ferro
- Text
- Al-Maqāma al-Māristāniyya, fully vocalised, as ar.wikisource gives it (revision 601165), with twenty typing slips corrected, its paragraphs divided and its Qurʾān quotations set between ﴿ ﴾ · Badīʿ al-Zamān al-Hamadhānī · public domain
- The note on the text, the Latin title line and the colophon · Postext Cookbook · original
- Fonts
- Amiri (SIL OFL 1.1) · Aref Ruqaa (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


