Skip to main content
Recipe number 114

Cookbook · Chapter 1 · Page & grid

A Bulaq page: the text framed by its commentary

Ibn ʿAqīl’s grammar commentary in the main column, glosses in the outer side column beside the passages they explain, all inside a double ruled frame.

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

pp. ٢–٣ · 2–3 of 6

  • Trim 170 × 240 mm
  • Column and a half, 7 mm gutter
  • Amiri 12.5/22
  • Aref Ruqaa
  • 6 pages
  • Level
  • Postext 1.65.0
  • Laid out in 138 ms
  • 139 lines of code

In short

A page made like the Arabic books printed in Cairo in the 1800s: the main text in the middle, short notes on it in a narrow column at the edge, and the whole page boxed in by printed lines.

What you'll build

Six pages set the way the Bulaq press and its Cairo successors printed a commentary in the nineteenth century. Ibn ʿAqīl’s explanation of the first verses of the Alfiyya, Ibn Mālik’s grammar in a thousand lines, runs in the main column, the verses in red; in the outer margin stands a ḥāshiya, short glosses that each open with the words of the text they explain, beside the passage they belong to. A double rule frames the type area, with a band at its head for the chapter and the folio, and a single rule parts the text from its margin. A real Bulaq page wraps the ḥāshiya round three sides of the text; Postext sets it on one side only, and this recipe says so.

This recipe answers

  • How do I lay out a Bulaq page, with the commentary framed around the text?

The short answer

script.js · lines 31–45in full code
// 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'. A gloss is written before the passage it
// explains and starts level with its first line, on the page where that passage goes on
// (sideAtColumnEnd: 'after'). 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', sideAtColumnEnd: 'after',
  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 } };

The commentary's column beside the text, both inside one ruled frame

Ingredients

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

Method

#1 · The ḥāshiya in a side column of its own

The code is the short answer above. A column-and-a-half layout whose side column takes only floats keeps the commentary out of the text’s flow: each gloss is a :::callout{type="hashiya" span="side"} written before the passage it explains, and it starts level with that passage's first line; sideAtColumnEnd: 'after' keeps it beside the passage when the passage goes on to the next page (Layout). The box has no background, border or padding, so it reads as text set in the margin, its lemma in bold, which the boldColor turns red. sideColumnSide: 'outer' puts the column at the fore-edge of both pages: on the right of the even page, which lies on the right in a book bound on the right.

Page 2: the gloss on «كديز» starts level with the paragraph that uses the word, at the outer edge, behind the column rule.

#2 · A frame drawn for each side of the spread

script.js · lines 49–79in full code
// 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. A heading's design is set in the flow
// and mirrored with the page (inFlow): there 'left' is the sheet's right.
const frame = (parity, withBand = true, inFlow = false) => {
  const left = (parity === 'even') !== inFlow ? 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. The frame stands off the
// sheet's centre by half the difference of the margins, towards the outer edge.
const SHIFT = (M.inner - M.outer) / 2; // mm
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-even', '{chapterTitle}', 'even', 'top', SHIFT),
  band('head-odd', '{chapterTitle}', 'odd', 'top', -SHIFT),
  band('folio-even', '{pageNumber}', 'even', 'top-right', -(M.outer + 1), { pages: 'all' }),
  band('folio-odd', '{pageNumber}', 'odd', 'top-left', M.outer + 1, { pages: 'all' })] };

The frame is three page design elements in the header: two boxes with a border and no fill, 1.3 mm apart, and a rule under the band that holds the running head. Page elements are physical, so the frame is built twice, once per parity, from the margins of that side (Page order and right binding). The folio sits at the outer end of the band on every page, openers included; the chapter title is centred and left off the opener, where the title itself stands under it.

#3 · A title page inside the same frame

script.js · lines 83–101in full code
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'),
  // Centred in the frame: the title page is an odd page set in the mirrored flow.
  placement: { anchor: { to: 'page', edge: 'top' }, offset: { x: mm(SHIFT), 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, true),
    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: { x: mm(SHIFT), 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') }),
  ] } } };

The title page reuses the frame without its band. A heading's design is set in the flow and mirrored with the page, so there the frame is built with its sides swapped (inFlow): its left is the sheet's right. Its lines come from heading attributes, on and margin, so the whole title page is one line of Markdown, and the Latin line under them changes with the edition.

The whole recipe

Sandbox
// ═══ 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.28.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 = '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'. A gloss is written before the passage it
// explains and starts level with its first line, on the page where that passage goes on
// (sideAtColumnEnd: 'after'). 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', sideAtColumnEnd: 'after',
  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

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

#Put the commentary on the inner side

Some presses set the ḥāshiya by the spine, so the text keeps the wider outer margin.

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

#Box each gloss

A thin rule round each gloss, as some later Cairo prints have, is the callout’s own border.

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

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
  • 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 · public domain
  • The glosses in the margin, the title page, the note on the text and the colophon · Postext Cookbook · original
Fonts
Amiri (SIL OFL 1.1) · Aref Ruqaa (SIL OFL 1.1)
SandboxPDF