In short
The opening of Ibn Khaldūn’s Muqaddima as a modern Arabic scholarly edition: introduction pages numbered with letters, the text with digits, and footnotes that count from one again on every page.
What you'll build
Eleven pages of a modern Arabic critical edition, a taḥqīq, of the first section of Ibn Khaldūn’s Muqaddima, on the excellence of history. The front matter is folioed in abjad letters, as Cairo and Beirut editions do: a title page أ, its imprint ب, then the editor’s introduction ج and د. The text starts again at ١ on the next recto. The editor’s notes stand at the foot of each page, numbered (١), (٢), (٣) and starting again on every page, under a short rule on the right; they gloss rare words, identify the people and places Ibn Khaldūn names and give the sūra and verse of each Qurʾān quotation. An index of names closes the book, sorted as Arabic indexes are, without the article ال. The notes and the introduction are written for this recipe.
This recipe answers
- How do I number the front matter of an Arabic book in abjad letters (أ، ب، ج)?
- How do I number Arabic footnotes per page, in parentheses: (١)?
The short answer
// The page counter starts in abjad letters: the title page is أ, its back ب, the editor's
// introduction ج and د. Before the text, two directives in the Markdown count again from 1,
// in the document's digits (١ ٢ ٣ in an `ar` document), on the next odd page:
// :::pagebreak{parity="odd"}
// :::numbering{format="arabic-indic" startAt=1}
// {pageNumber} prints each page's own label, so one footer and one header serve both runs.
const pageNumbering = { format: 'abjad', startAt: 1 }; // أ ب ج د هـ و ز ح…
// The editor's notes: numbered again on every page, written «(١)», raised after the word in
// the text and on the line at the head of the note. The rule over the notes and each note's
// number stand on the start side, the right, because the page runs right to left.
const footnotes = {
numbering: 'page', markerTemplate: '({n})', noteNumberPosition: 'inline',
fontSize: pt(10.5), lineHeight: pt(18.5), color: col('ink'), textAlign: 'justify',
spaceAbove: pt(14), spaceBelowRule: pt(6),
separator: { width: 0.28, lineWidth: pt(0.6), color: col('rule') },
};
Abjad folios for the front matter, Arabic-Indic from the text, notes (١)
Ingredients
- Features
- FootnotesArabic numbering stylesRoman front matterDigits of the generated numbersRight-to-left textBooks bound on the rightArabic fontsArabic as the document languageHeading stylesHeading attributesDesigned openersRunning heads and foliosHeads by page roleBack-of-book indexIndex sorted without the articleParagraph stylesSemantic colour palettePDF exportFonts embedded in the PDF
- Also uses
- Paper colourPage and column breaksSection geometryRunning heads per sectionUnnumbered chapters
- Type
- Amiri, Aref Ruqaa (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · Two runs of folios and notes per page
The code is the short answer above. page.pageNumbering starts the book in 'abjad', the letters in abjad order, with هـ for five. Before the text two directives start the count again on the next odd page in the document’s digits (:::numbering, Digits and numeral styles). The notes take numbering: 'page', a markerTemplate of '({n})' and noteNumberPosition: 'inline', so the marker is raised in the text and the note opens with its number on the line (Footnotes).

#2 · An index that skips the article
// Marks in the text, `:index[المسعودي]`, `:index[الطّبريّ]{term="الطبري"}`. With
// ignoreArticle, المسعودي files under م and الطبري under ط; ابن الكلبي stays under ا.
// It is the default when the index sorts in Arabic: written out here to say so.
const index = { ignoreArticle: true, fontFamily: NASKH, fontSize: pt(11), lineHeight: pt(17),
color: col('ink'), groups: { fontFamily: NASKH, fontWeight: 700, fontSize: pt(13),
color: col('accent'), marginTop: pt(8) } };
const indexStyle = { id: 'index', numbered: false, toc: false, span: 'page',
breakBefore: { enabled: true, parity: 'any' },
layout: { layoutType: 'double', gutterWidth: mm(10) } }; // two columns under the title
Names are marked in the text, :index[المسعودي], and :::index prints them at the end. With ignoreArticle, المسعودي files under م and الطبري under ط, while ابن إسحاق stays under ا; a see-reference sends إسرائيل to يعقوب (Contents and index). The page numbers in the index are the labels of the pages, so a name from the introduction reads ج.
#3 · Running heads over a rule
// Running heads are physical. In a book bound on the right the verso (even) is the right
// page: its outer edge, the folio's, is the right one, and its text block starts INNER mm
// from the left edge; the recto (odd) mirrors it.
const HEAD_Y = 14; // mm from the trim
const blockX = (parity) => (parity === 'even' ? INNER : OUTER); // the text block's left edge
const heads = (parity, content) => [
text(`${parity}-head`, content, NASKH, 10.5,
{ ...at('top-left', blockX(parity), HEAD_Y, 'page'), size: { width: mm(MEASURE) } },
{ color: col('muted'), parity, pages: 'body' }),
text(`${parity}-folio`, '{pageNumber}', NASKH, 11.5, parity === 'even'
? at('top-right', -OUTER, HEAD_Y, 'page') : at('top-left', OUTER, HEAD_Y, 'page'),
{ parity, pages: 'body', align: parity === 'even' ? 'right' : 'left' }),
{ ...rule(`${parity}-rule`, HEAD_Y + 7, MEASURE, 'top-left', 'page', blockX(parity)),
parity, pages: 'body' },
];
const header = { elements: [...heads('even', '{title}'), ...heads('odd', '{chapterTitle}')] };
const dropFolio = (pages) => text(`folio-${pages}`, '{pageNumber}', NASKH, 11.5,
at('bottom', 0, -12, 'page'), { pages });
const footer = { elements: [dropFolio('opener')] }; // on the openers, under the text
// Front matter: no running heads, the abjad folio centred at the foot of every page.
const front = { id: 'front', numbered: false, toc: false,
breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
footer: { elements: [dropFolio('all')] }, advancedDesign: titleOnly(22) };
The verso carries the book’s title and the recto the section, over a hairline the width of the text block, with the folio at the outer end. 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). Openers and the front matter take a folio centred at the foot instead.
#4 · A title page and its imprint
const onPage = (y) => at('top', 0, y, 'page');
const blind = { numbered: false, toc: false, span: 'page', runningChapter: false,
breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
footer: { elements: [] } }; // blind folios: أ and ب count, but do not print
const titlePage = { id: 'title', ...blind, advancedDesign: design([
text('book', '{attr.book}', NASKH, 14, onPage(44), { color: col('muted') }),
rule('rule-top', 58, 40, 'top', 'page'),
text('title', '{titleText}', RUQAA, 44, onPage(64), { fontWeight: 700,
color: col('accent'), lineHeight: 1.3 }),
rule('rule-foot', 92, 40, 'top', 'page'),
text('author', 'تأليف {author}', NASKH, 15, onPage(100), { fontWeight: 700 }),
text('years', '{attr.years}', NASKH, 12, onPage(110)),
text('part', '{attr.part}: {subtitle}', NASKH, 13, onPage(132)),
text('editor', '{attr.editor}', NASKH, 12, onPage(178), { color: col('accent') }),
text('latin', '{attr.latin}', NASKH, 9.5, { ...onPage(196), size: { width: mm(110) } },
{ color: col('muted'), direction: 'ltr' }), // a Latin line: its own direction
], 0) };
const imprintPage = { id: 'imprint', ...blind, advancedDesign: design([
text('edition', '{attr.edition}', NASKH, 11, onPage(170)),
text('imprint', '{attr.imprint}', NASKH, 9, { ...onPage(180), size: { width: mm(100) } },
{ color: col('muted'), lineHeight: 1.45, direction: 'ltr' }),
], 0) };
The title page and the imprint on its back are heading styles with nothing in the flow: their lines come from heading attributes, so the imprint’s Latin lines, which change with the edition, are one attribute in the Markdown.
The whole recipe
// ═══ Postext Cookbook · Nº 113 · A critical edition (taḥqīq) with notes per page ═══════
// https://postext.dev/en/cookbook/tahqiq-critical-edition
// Code: MIT · Text: Ibn Khaldūn, al-Muqaddima, ar.wikisource (PD) · Pictures: none
// Fonts: Amiri, Aref Ruqaa (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 = 'tahqiq-critical-edition';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// A modern Cairo taḥqīq: black Naskh on a cream paper, headings and rules in one dark red.
const palette = {
ink: '#1e1a16', // text and notes: a warm near-black
accent: '#8a2a1d', // headings, the title, the index letters
rule: '#8c7a62', // hairlines: the rule under the running heads, the rule over the notes
muted: '#5e564c', // running heads, the imprint
paper: '#fbf8f0', // 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'; // text, notes, headings in bold, running heads, index
const RUQAA = 'Aref Ruqaa'; // display: the title on the title page
const [W, H] = [170, 240]; // mm: 17 × 24 cm, the size of most Cairo and Beirut editions
const [TOP, INNER, OUTER] = [22, 20, 16]; // mm; `left` is the inner margin on both pages
const MEASURE = W - INNER - OUTER; // 134 mm
const [SIZE, LEAD] = [13, 22.5]; // pt: 1.73 ×, so the few vowels marked clear the line above
// #region answer: abjad folios for the front matter, Arabic-Indic from the text, notes (١)
// The page counter starts in abjad letters: the title page is أ, its back ب, the editor's
// introduction ج and د. Before the text, two directives in the Markdown count again from 1,
// in the document's digits (١ ٢ ٣ in an `ar` document), on the next odd page:
// :::pagebreak{parity="odd"}
// :::numbering{format="arabic-indic" startAt=1}
// {pageNumber} prints each page's own label, so one footer and one header serve both runs.
const pageNumbering = { format: 'abjad', startAt: 1 }; // أ ب ج د هـ و ز ح…
// The editor's notes: numbered again on every page, written «(١)», raised after the word in
// the text and on the line at the head of the note. The rule over the notes and each note's
// number stand on the start side, the right, because the page runs right to left.
const footnotes = {
numbering: 'page', markerTemplate: '({n})', noteNumberPosition: 'inline',
fontSize: pt(10.5), lineHeight: pt(18.5), color: col('ink'), textAlign: 'justify',
spaceAbove: pt(14), spaceBelowRule: pt(6),
separator: { width: 0.28, lineWidth: pt(0.6), color: col('rule') },
};
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
#Use the abjad numerals
'arabic-abjad' writes the additive abjad numerals instead of the plain letter series: the eleventh page is يا, not ك.
-const pageNumbering = { format: 'abjad', startAt: 1 }; // أ ب ج د هـ و ز ح…
+const pageNumbering = { format: 'arabic-abjad', startAt: 1 }; // … ط ي يا يب#Number the notes through the section
numbering: 'chapter' counts the notes on from page to page, as some older editions do.
- numbering: 'page', markerTemplate: '({n})', noteNumberPosition: 'inline',
+ numbering: 'chapter', markerTemplate: '({n})', noteNumberPosition: 'inline',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 →
Pitfall
:::numbering takes effect at the next page
:::numbering changes the count from the next page that starts, not the current one. Put it right after a :::pagebreak (parity odd before chapter one) so the new numbering begins where you mean. Roman front matter →
Credits
- Recipe
- Ignacio Ferro
- Text
- The opening section of the Muqaddima, “On the excellence of history”, as ar.wikisource gives it (revision 610595), without its notes · Ibn Khaldūn · public domain
- The editor’s introduction in Arabic, the notes, the index and the imprint · 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)


