Skip to main content
Recipe number 34

Cookbook · Chapter 7 · Figures & images

Catalogue entries facing their plates

Each entry opens a verso and cites its plate in the commentary’s first sentence; the plate floats to the facing recto, scaled to fill the text block.

pp. 4–5 of 8

  • Trim 230 × 280 mm
  • Column and a half, 7 mm gutter
  • Ibarra Real Nova 11.5/16
  • Libre Bodoni
  • Sofia Sans Condensed
  • 8 pages
  • Level
  • Postext 1.57.1
  • Laid out in 56 ms
  • 246 lines of code

In short

A small exhibition catalogue of three old book illustrations of Don Quixote. Each description sits on a left-hand page, with its picture filling the right-hand page opposite.

What you'll build

A small catalogue for a cabinet exhibition of three wood engravings from Gustave Doré’s Don Quixote (Paris, 1863), on a 230 × 280 mm page. The cover sets DORÉ in 88-pt Libre Bodoni on warm black, under a framed detail of the windmills plate. Each entry opens a left-hand page with a sepia catalogue number beside an italic title, the tombstone in the outer column, a lead with a three-line drop cap, and the commentary. The commentary’s first sentence cites the plate, which opens the right-hand page opposite, centred and scaled until plate, caption and credit line fill the text block, 215 mm tall. The last page is a checklist with a thumbnail in the first cell of each row and the page on which each plate prints.

This recipe answers

  • How do I make an art catalogue: entry on the left page, plate on the facing right page?
  • How do I control where a figure goes: top of page, across both columns, exactly here, or in the margin?
  • How do I put pictures or icons inside table cells?
  • How do I add an author line, a standfirst or a lead with a drop cap to an opener?

The short answer

script.js · lines 38–60in full code
// Each entry breaks to a verso and cites its plate in the commentary's first sentence; a 'top'
// float never lands on its citing page (gotcha: top-float-next-page), so it opens the recto.
const entryLevel = () => ({
  level: 1, span: 'page', numberingTemplate: '{1}', // {number} in the opener: Cat. 1, 2, 3
  breakBefore: { enabled: true, parity: 'even' }, // an entry opens a verso, facing its plate
  marginBottom: pt(LEAD), advancedDesign: entryOpener(),
  dropCap: { lines: 3, fontFamily: DISPLAY, color: col('sepia'), gap: mm(1.6) }, // the lead's
});
const plateType = {
  id: 'plate', name: 'Cat.', shortLabel: 'Cat.', captionPrefix: 'Cat.', // 'Cat. 1. …'
  numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal',
  // A plate taller than the recto's text block is scaled, proportions kept, until plate, caption
  // and credit line fit it; the caption takes the plate's width, and both are centred.
  defaultPlacement: { position: 'top', span: 'page', align: 'center',
    shrink: 'page', minScale: 0.5, captionMeasure: 'body' },
};
// Under the plate (pt): a caption and a credit line, and their gaps.
const CAPTION = { size: 8.5, gap: 6, note: 7.2, noteGap: 1.5 };
const plate = ({ id, file, caption, altText }, [pxW, pxH]) => ({
  id, typeId: 'plate', kind: 'bitmap', caption, note: CREDIT, altText,
  // The print master's pixels, about 283 dpi at this size (gotcha: bitmap-print-size).
  bitmap: { fileId: file, format: 'jpeg', width: pxW, height: pxH }, createdAt: 0, updatedAt: 0,
});

A Plate type that floats to the head of the facing recto, sized to fill it

Ingredients

Type
Ibarra Real Nova, Libre Bodoni, Sofia Sans Condensed (SIL OFL 1.1)
Assets
  • library-835.jpg
  • vigil-835.jpg
  • windmills-835.jpg
  • windmills-detail-540.jpg
  • Cat. 1, Don Quixote in His Library (Part I, ch. I), wood engraving by Héliodore Pisan after Gustave Doré, 1863; scan from Wikimedia Commons, reduced to 835 px wide (Gustave Doré · Héliodore Pisan, public domain)
  • Cat. 2, The Vigil of Arms (Part I, ch. III), wood engraving by Héliodore Pisan after Gustave Doré, 1863; scan from Wikimedia Commons, reduced to 835 px wide (Gustave Doré · Héliodore Pisan, public domain)
  • Cat. 3, The Adventure of the Windmills (Part I, ch. VIII), wood engraving by Héliodore Pisan after Gustave Doré, 1863; scan from Wikimedia Commons, reduced to 835 px wide (Gustave Doré · Héliodore Pisan, public domain)
  • The cover’s detail of Cat. 3: a 1,100-px square cut from the same scan and reduced to 540 px (Gustave Doré · Héliodore Pisan, public domain)

Method

#1 · The plate waits for the page opposite

The code is the short answer above. Every entry breaks to an even page, and a top float never lands on the page that cites it, so the plate cited in the commentary’s first sentence skips the verso and opens the recto facing it. The plate type’s defaultPlacement asks for shrink: 'page': at the full measure a plate would stand 242 mm tall, more than the recto’s text block holds, so Postext scales it, keeping its proportions, until plate, caption and credit line fit the band left above the float gap (placement). minScale: 0.5 would let a plate go down to half its width; here each keeps about nine tenths of it. captionMeasure: 'body' sets the caption and credit line at the plate’s width, and align: 'center' centres both on the page.

#2 · The entry’s head comes from its heading

script.js · lines 81–113in full code
const [KICKER, NUMERAL] = [8.5, { size: 80, y: 7 }]; // pt: labels; the numeral, y in mm
const TITLE = { size: 30, lineHeight: 1.08 }; // pt; a multiple of the size
const HEAD_RULE = NUMERAL.y + NUMERAL.size * PT + 3; // mm: the hairline under the numeral
// mm: the lead, the entry's first paragraph, 5 mm under the hairline on the next grid line;
// the opener ends a line above it (the level's marginBottom), and the tombstone faces it.
const LEAD_Y = Math.ceil((HEAD_RULE + 5) / PT / LEAD) * LEAD * PT;
const [LEADIN, TOMB] = [{ size: 13.5, lead: 19 }, { size: 8.5, lead: 12.5 }]; // pt
const BASE = 0.8; // a line's first baseline stands 0.8 down its line box
// em: Libre Bodoni's capitals, and its figures, which stop short of them ('1': 0.716)
const [CAP_HEIGHT, FIGURE_HEIGHT] = [0.754, 0.716];
const inkTop = (size, lineHeight, height) => (BASE * lineHeight - height) * size; // pt to the ink
// The title's capitals level with the numeral's figures: 1.2 mm below the numeral's top.
const TITLE_Y = NUMERAL.y + (inkTop(NUMERAL.size, 1, FIGURE_HEIGHT)
  - inkTop(TITLE.size, TITLE.lineHeight, CAP_HEIGHT)) * PT;
// Entries open on versos, whose outer column is on the left: the side column is at x = 0.
const head = (label, numeral) => [
  text('label', label, LABEL, KICKER, 'sepia', at('container', 'top-left', 0, 0), caps(KICKER)),
  text('numeral', numeral, DISPLAY, NUMERAL.size, 'sepia',
    at('container', 'top-left', 0, NUMERAL.y, SIDE), { lineHeight: 1 }),
  text('title', '{titleText}', DISPLAY, TITLE.size, 'ink', at('container', 'top-left', MAIN_X,
    TITLE_Y, MAIN), { italic: true, lineHeight: TITLE.lineHeight }),
  { kind: 'rule', id: 'head-rule', direction: 'horizontal', thickness: pt(0.5), color: col('rule'),
    placement: at('container', 'top-left', 0, HEAD_RULE, 'fill') },
];
const entryOpener = () => ({ enabled: true, minHeight: mm(LEAD_Y - LEAD * PT),
  slot: { elements: [...head('Cat.', '{number}'),
  text('chapter', '{attr.chapter}', LABEL, KICKER, 'sepia',
    at('container', 'top-left', MAIN_X, 0, MAIN), caps(KICKER)),
  // Baseline on the lead's; the attribute's \n breaks give its three lines.
  text('tombstone', '{attr.tombstone}', LABEL, TOMB.size, 'muted',
    at('container', 'top-left', 0, LEAD_Y + BASE * (LEADIN.lead - TOMB.lead) * PT, SIDE - 6),
    { lineHeight: TOMB.lead / TOMB.size, reserve: false }), // beside the lead: no room of its own
] } });

Each # heading carries its chapter and tombstone as attributes, and the opener’s design slot draws them. The large number is the heading’s own {number} from numberingTemplate: '{1}'; with one plate to an entry it runs 1, 2, 3 in step with the plates’ Cat. counter. The lead is the entry’s first paragraph, in a :::paragraphs{style="lead"} group at 13.5 pt, and the level’s dropCap opens it with a three-line sepia initial whose top meets the capitals of the first line and whose foot sits on the third baseline, both cap heights measured from the faces (drop caps). The lead is set ragged: justified at this size, its few words a line opened past the commentary’s 1.5×. minHeight ends the opener a line above LEAD_Y, the grid line where the lead starts, the tombstone faces the lead’s first line without taking room of its own (reserve: false), and a :::space under the lead starts the commentary flush a line lower. TITLE_Y sets the title 1.2 mm lower than the numeral, which lines its capitals up with the numeral’s figures: in Libre Bodoni the figures are 0.716 em tall and the capitals 0.754 em.

#3 · Declare the master, draw a smaller copy

script.js · lines 316–333in full code
// plate() sizes each plate from its master, the Commons scan at 2,400 px tall (MASTER_PX);
// the canvas draws the registered 835-px copy (the block's width on a 1,000-px page) in that box.
async function scan(file) {
  const res = await fetch(asset(file));
  if (!res.ok) throw new Error(`Scan not found (${res.status}): ${file}`);
  return createImageBitmap(await res.blob());
}
async function loadPlates() {
  const [detail, ...scans] = await Promise.all([DETAIL, ...PLATES.map((p) => p.file)].map(scan));
  const resources = [checklist(PLATES), picture('cover-detail', onPaper(detail),
    'Detail of Cat. 3: the knight and his horse caught on the sail.')];
  for (const [i, p] of PLATES.entries()) {
    registerResourceImage(p.file, onPaper(scans[i]));
    resources.push(plate(p, MASTER_PX[p.id]), // and a thumbnail: its own small file and size
      picture(`${p.id}-thumb`, onPaper(await resized(scans[i], THUMB_PX)), p.altText));
  }
  return resources;
}

Postext sizes a bitmap from the pixels it declares, at the document’s dpi, and never prints it wider than those pixels allow. plate() declares each plate’s master, the Commons scan reduced to 2,400 px tall: 1,900 × 2,400 px for Cat. 1, which could reach 322 mm at page.dpi: 150. The text block therefore sets the size, 215 mm tall, and at that height 2,400 px come to about 283 dpi. At the default 300 dpi the plate would stop at 161 mm wide. The canvas draws whatever picture is registered into that box, so the pen fetches the three 835-px copies in assets/, 0.97 MB against 5.8 MB for the masters. Drawn from the 2,400-px masters instead, the skies fill with moiré bands and the capture’s images grow by about 0.3 MB, past the Cookbook’s 1.4 MB limit.

#4 · A cover from a heading style

script.js · lines 117–141in full code
const DETAIL = 'windmills-detail-540.jpg'; // a square cut from Cat. 3, at its size on screen
const FRAME = { w: 124, y: 40, pad: 3.5 }; // mm: the picture, its top, the hairline's inset
const FRAME_X = (TRIM.w - FRAME.w) / 2;
const NAME = { size: 88, track: 8, y: 176 }; // pt, pt, mm
const centred = (id, content, family, size, color, y, more) => text(id, content, family,
  size, color, at('page', 'top', 0, y, 'fill'), { align: 'center', ...more });
const coverStyle = () => ({
  id: 'cover', numbered: false, header: { elements: [] }, footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [ // painted in this order
    { kind: 'box', id: 'night', style: { backgroundColor: col('night') },
      placement: { ...at('bleed', 'top-left', 0, 0), size: { width: 'fill', height: 'fill' } } },
    { kind: 'box', id: 'frame', style: { borderColor: col('gilt'), borderWidth: pt(0.5) },
      placement: { ...at('page', 'top-left', FRAME_X - FRAME.pad, FRAME.y - FRAME.pad),
        size: { width: mm(FRAME.w + 2 * FRAME.pad), height: mm(FRAME.w + 2 * FRAME.pad) } } },
    { kind: 'image', id: 'detail', resourceId: 'cover-detail',
      placement: at('page', 'top-left', FRAME_X, FRAME.y, FRAME.w) },
    centred('kicker', '{attr.kicker}', LABEL, 8.5, 'gilt', 18, caps(8.5)),
    // Tracked capitals centre on their letters: the tracking after the É is left out.
    centred('name', '{titleText}', DISPLAY, NAME.size, 'paper', NAME.y, { lineHeight: 1,
      textTransform: 'uppercase', letterSpacing: pt(NAME.track) }),
    centred('subtitle', '{attr.subtitle}', DISPLAY, 18, 'paper', NAME.y + NAME.size * PT + 4,
      { italic: true }),
    centred('foot', '{attr.foot}', LABEL, 8.5, 'gilt', 250, caps(8.5)),
  ] } },
});

The cover is the first heading, # Doré {style="cover" …}, drawn by a style without folios. Its image element draws windmills-detail-540.jpg, registered as a resource that no paragraph cites, so it gets no number and no caption. The file is a 1,100-px square cut from the windmills scan and reduced to 540 px, its width on a 1,000-px page. The name is tracked 8 pt, and the tracking after its last letter is left out of the centring, so the four capitals sit on the page’s centre line with no offset.

#5 · Thumbnails in the checklist’s cells

script.js · lines 145–167in full code
const THUMB_PX = 300; // px wide: 25 mm at 300 dpi, about the width the cell prints it
// The entries' head, label and numeral from attributes; the level gives span, break and margin.
const checklistStyle = () => ({ id: 'checklist', numbered: false, dropCap: false, // no initial
  advancedDesign: { enabled: true, slot: { elements: head('{attr.kicker}', '{attr.range}') } } });
const cell = (content, more) => ({ content, verticalAlign: 'middle', ...more });
const checklist = (plates) => ({
  id: 'checklist', typeId: 'list', kind: 'table', placement: { position: 'here' },
  altText: 'Checklist of the three works with thumbnails, titles, chapters and pages.',
  table: { model: { headerRowCount: 1, columnWidths: [26, 9, 70, 11], rows: [
    ['', 'Cat.', 'Work and chapter', 'Page'].map((label, i) =>
      cell(label, { isHeader: true, align: i === 3 ? 'right' : 'left' })),
    ...plates.map((p, i) => [
      { content: '', image: { resourceId: `${p.id}-thumb` } },
      cell(String(i + 1)), cell(`*${p.caption}*. ${p.illustrates}`),
      cell(String(platePage(i + 1)), { align: 'right' }),
    ]),
  ] } },
  createdAt: 0, updatedAt: 0,
});
// The cover is page 1 and entry n opens page 2n, so its plate prints on page 2n + 1.
const platePage = (n) => 2 * n + 1;
const listType = { id: 'list', name: 'List', shortLabel: 'List', captionPrefix: '', // no caption
  numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' };

A cell’s image fits a bitmap resource to the cell’s inner width, 23 mm here. Each thumbnail is its own 300-px copy, declared at that size, rather than the 835-px plate scaled down at draw time. The table has no caption text and its type an empty caption prefix, so no caption is drawn. The checklist style sets only numbered: false and its design, and takes the page span, the break to a verso and the bottom margin from level 1.

#6 · Stop when an entry outgrows its page

script.js · lines 349–354in full code
const astray = doc.pages.find((pg) => pg.role !== 'opener' && !pg.floats?.length);
if (astray) { // text run past its verso, or the blank page that follows it
  const error = new Error(`Page ${astray.pageLabel} holds no plate: shorten the entry before it.`);
  kitFail(error); // the viewer's bar says why
  throw error;
}

An entry that runs past its verso still sends its plate to the next page. The rest of its commentary then follows the plate, and a blank page keeps the next entry on a verso, so every later plate prints two pages after the page the checklist gives for it. The check stops the build at the first page that is not an opener and holds no plate, and shows that page’s number in the viewer’s bar.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 034 · Catalogue entries facing their plates ══════════════
// https://postext.dev/en/cookbook/catalogue-facing-plates
// Code: MIT · Text: original (CC BY 4.0), Ormsby 1885 (PD) · Plates: Doré and Pisan, 1863 (PD)
// Fonts: Ibarra Real Nova, Libre Bodoni, Sofia Sans Condensed (OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en')
const RECIPE = 'catalogue-facing-plates';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = {
  ink: '#1b1918', paper: '#faf7f1', night: '#2a2724', // text; the page and plates; the cover
  sepia: '#8a6a45', gilt: '#c9ad86', // the accent on paper (4.6:1) and on the night (6.9:1)
  rule: '#cfc6b8', muted: '#6c665e', // hairlines; tombstones, credit lines, folios
};
// col(id): a colour linked to its palette entry, with the entry's hex beside the id.
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' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'sepia (defaults)', value: { hex: palette.sepia, model: 'hex' } },
];
const [TEXT, DISPLAY, LABEL] = ['Ibarra Real Nova', 'Libre Bodoni', 'Sofia Sans Condensed'];
const PT = 25.4 / 72; // mm per point
const [SIZE, LEAD, LINES] = [11.5, 16, 41]; // body pt, leading pt; 41 lines make the text block
const TRIM = { w: 230, h: 280 }; // mm: a catalogue trim
const [TOP, INNER, OUTER] = [24, 20, 18]; // margins, mm
const BLOCK_W = TRIM.w - INNER - OUTER; // 192 mm: the text block, and the widest plate
const BLOCK_H = LINES * LEAD * PT; // 231.4 mm
const [SIDE_PC, GUTTER] = [34, 7]; // the outer column: 65.3 mm for numeral and tombstone; mm
const SIDE = (BLOCK_W * SIDE_PC) / 100;
const MAIN_X = SIDE + GUTTER; // mm from the block's outer edge to the text column
const MAIN = BLOCK_W - MAIN_X; // 119.7 mm: the measure, about 71 characters

// #region answer: a Plate type that floats to the head of the facing recto, sized to fill it
// Each entry breaks to a verso and cites its plate in the commentary's first sentence; a 'top'
// float never lands on its citing page (gotcha: top-float-next-page), so it opens the recto.
const entryLevel = () => ({
  level: 1, span: 'page', numberingTemplate: '{1}', // {number} in the opener: Cat. 1, 2, 3
  breakBefore: { enabled: true, parity: 'even' }, // an entry opens a verso, facing its plate
  marginBottom: pt(LEAD), advancedDesign: entryOpener(),
  dropCap: { lines: 3, fontFamily: DISPLAY, color: col('sepia'), gap: mm(1.6) }, // the lead's
});
const plateType = {
  id: 'plate', name: 'Cat.', shortLabel: 'Cat.', captionPrefix: 'Cat.', // 'Cat. 1. …'
  numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal',

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

#Leave air under the plates

A width fraction narrows the float itself: at 78 % of the text block every plate stands about 188 mm tall, centred, with about 27 mm of empty text block under its credit line, and none needs shrinking.

-  defaultPlacement: { position: 'top', span: 'page', align: 'center',
-    shrink: 'page', minScale: 0.5, captionMeasure: 'body' },
+  defaultPlacement: { position: 'top', span: 'page', align: 'center', width: 0.78 },

#Set figures in the outer column

For figures and glosses that stack in a float-only outer column beside the paragraph that cites them, see the textbook with a margin column.

Pitfalls

Pitfall

A 'top' float goes to the page after its citation unless it may head the citing page

By default a float never goes above its own reference, so a page-wide 'top' float cited on page N opens page N+1. Set placement.citingPage: true on the resource or its type's defaultPlacement (or layout.floatsAtCitingPage for the whole book, since postext 1.25) and it heads page N instead, the text above the reference moving down under it, when it fits within layout.maxTopFraction and the citing line stays on that page. It never heads a chapter's first page or a page after a forced break: there it still opens the next page, and 'auto' or 'bottom' can take the foot of the citing page. Figure placement →

Pitfall

Bitmaps take their print size from a resolution: declare it, not print-size pixels

A bitmap without a resolution is laid out one pixel per layout pixel at the document's dpi, so a 2400 px photo is 406 mm wide on a 150 dpi page. Declare the file's real pixels and give the picture its resolution (bitmap.resolution: 300), or set layout.bitmapResolution for every bitmap: a ppi, or 'file' to read the one the file states. The column still caps the picture. Figures and tables as resources →

Sandbox check · bitmapTooSmall

Low-resolution image

Why. A bitmap is drawn more than 1.5 times wider than its pixels, so it will look blurry in print.

Fix. Supply about 300 dpi at the printed size, and declare the bitmap's real width and height. Docs →

Credits

Text
Images
Fonts
Ibarra Real Nova (SIL OFL 1.1) · Libre Bodoni (SIL OFL 1.1) · Sofia Sans Condensed (SIL OFL 1.1)
Sandbox