In short
A nature magazine story that opens with a large photo across the top of the page. It shows how to lay out the title, short intro, author and photo credit, then side boxes and a small end sign.
What you'll build
The feature well of Boreal, a nature magazine's winter issue, on a 225 × 297 mm page. The story opens under a mountain lake bled across the top of the page. Below the picture, a tracked kicker tops a two-line headline, with an italic standfirst to its right and the byline under it; the photographer’s credit runs under the photo. The headline is the text of the Markdown heading, and the kicker, standfirst, byline and credit are its attributes. The story continues across a spread in two justified columns. The verso has a pull quote with a hanging quotation mark and a fact box at the head of the right-hand column; the recto, a band of pine wood at the top and a dark numbers panel at the foot. A small square ends the story. Overleaf, a field guide reuses the opener with a drawing and a rust kicker.
This recipe answers
- How do I add an author line, a standfirst or a lead with a drop cap to an opener?
- How do I give every chapter its own photo, colour or opener variant?
- How do I set an epigraph, a dedication, a signature, or a pull quote with a big quote mark?
The short answer
const TOP = 22; // top margin in mm: an opener's container starts here
const sans = { fontFamily: 'Instrument Sans', fontWeight: 600, textTransform: 'uppercase' };
const HEAD = 118; // mm: the headline's measure; the standfirst takes the rest of the line
// Empty padding paints nothing but counts: the story starts on the first grid line at least
// 5 mm under the lower of the headline and the byline, however many lines each one runs to.
const air = { padding: { bottom: mm(5) } };
const at = (id, edge, x, y, width) => ({ anchor: { to: id, edge },
offset: { x: mm(x), y: mm(y) }, ...(width && { size: { width: mm(width) } }) });
const opener = (resourceId, depth) => ({ // depth: how far down the page the picture bleeds
enabled: true, // no minHeight: the story starts under the headline and byline (see air)
slot: {
elements: [ // the photo is an element, not a float: no float reaches the trim
{ kind: 'image', id: 'photo', resourceId, placement: { anchor: { to: 'bleed',
edge: 'top-left' }, size: { width: 'fill', height: mm(depth) } } },
// The photo hangs from the page's top edge, the words from the container, TOP mm lower:
// depth − TOP is the photo's foot, so the credit sits 2 mm under it and the kicker 9 mm.
{ kind: 'text', id: 'credit', content: '{attr.credit}', ...sans, fontWeight: 500,
fontSize: pt(6.5), letterSpacing: pt(0.6), color: col('muted'), align: 'right',
placement: at('container', 'top-right', 0, depth - TOP + 2) },
{ kind: 'text', id: 'kicker', content: '{attr.kicker}', ...sans, fontSize: pt(8.5),
letterSpacing: pt(1.7), color: col('lake'), align: 'left',
placement: at('container', 'top-left', 0, depth - TOP + 9) },
{ kind: 'text', id: 'headline', content: '{titleText}', fontFamily: 'Instrument Serif',
fontSize: pt(58), color: col('ink'), align: 'left', box: air, // wraps: a heading design
lineHeight: 0.94, // tight: the two lines of the headline nearly touch
placement: at('#kicker', 'below', 0, 2.5, HEAD) },
{ kind: 'text', id: 'standfirst', content: '{attr.standfirst}', italic: true,
fontFamily: 'Instrument Serif', fontSize: pt(13.5), lineHeight: 1.22, // a multiple
color: col('ink'), align: 'left',
placement: at('#headline', 'right-of', 7, 3.2) }, // wraps at the container's edge
{ kind: 'text', id: 'byline', content: '{attr.byline}', ...sans, fontSize: pt(7.5),
letterSpacing: pt(1.3), color: col('ink'), align: 'left', box: air,
placement: at('#standfirst', 'below', 0, 3.5) },
],
},
}); // hook-up: headings.levels[0] = { level: 1, span: 'page', breakBefore, advancedDesign:
// opener('lake', 160) }. {titleText} prints the heading's text, {attr.<key>} its <key>="…":
// # The Lake That Keeps Time {kicker="…" standfirst="…" byline="…" credit="…"}
A bleed photo, then the heading's kicker, headline, standfirst, byline and credit
Ingredients
- Features
- Designed openersPictures in page designsHeading attributesFloated boxesColumns in a box or in the textInline chipsChapters that open on a rectoFull-width chapter bandRunning heads and foliosColumn balancingFigure placementAnchoring design elementsBox icons and corner badgesCallout boxesFigures and tables as resourcesHeading stylesSemantic colour paletteHeads by page roleSource and credit linesColours per part
- Type
- Literata, Instrument Serif, Instrument Sans (SIL OFL 1.1)
- Assets
lake-2000.jpgthaw-2000.jpg- Clouds mirrored in a mountain lake (the opener photograph) (Ales Krivec, CC0 1.0)
- Walk in a thawing forest (the photo band) (Hannah Donze, CC0 1.0)
Method
#1 · Build the opener from the heading line
The code is the short answer above. Each {attr.<key>} prints the <key>="…" value on the story’s # line and {titleText} prints the heading itself (heading attributes), so each story keeps its words in its own Markdown and every level-1 heading shares one design. The photo hangs from the page’s top edge and the container starts 22 mm lower, so depth - TOP is the photo’s lower edge measured from the container; the credit sits 2 mm below that line at the top-right and the kicker 9 mm below it at the top-left. The headline goes below the kicker, set to the 118 mm HEAD measure. The standfirst goes right-of the headline with no width of its own, so it wraps at the container’s edge, and the byline goes below the standfirst, so a longer standfirst pushes the byline down instead of running into it. The level has no minHeight. The headline and the byline each end in an empty 5 mm padding that counts toward the opener’s height, so the story starts on the first grid line at least 5 mm under whichever of the two ends lower, however many lines each runs to.
#2 · Declare the pictures once, by their real pixels
// The pictures are not numbered: their own type, with an empty caption prefix and template,
// keeps a figure number off the pine wood's caption.
const photoType = { id: 'photo', name: t({ en: 'Photograph', es: 'Fotografía' }),
shortLabel: t({ en: 'photo', es: 'foto' }), captionPrefix: '', numberingTemplate: '',
resetOn: 'never', counterFormat: 'decimal' };
const PX = 10; // the drawing's pixels per mm
const resources = [
{ id: 'lake', typeId: 'photo', kind: 'bitmap', createdAt: 0, updatedAt: 0, // never cited:
// the opener fits it inside its box, so the JPEG is cropped to the box, 225 × 160 mm
bitmap: { fileId: 'lake-2000.jpg', format: 'jpeg', width: 2000, height: 1422 },
altText: t({ en: 'A still mountain lake mirroring clouds between autumn slopes.',
es: 'Un lago de montaña en calma que refleja las nubes entre laderas otoñales.' }) },
{ id: 'thaw', typeId: 'photo', kind: 'bitmap', createdAt: 0, updatedAt: 0,
// Pixels at the page's 150 dpi (gotcha: bitmap-print-size): 2000 px make 339 mm, so the
// band shrinks to the 195 mm measure. At 300 dpi it would print 169 mm wide.
bitmap: { fileId: 'thaw-2000.jpg', format: 'jpeg', width: 2000, height: 944 },
// A top float opens the page after its ::resource line (gotcha: top-float-next-page):
// the line sits on the verso, so the band heads the recto.
placement: { position: 'top', span: 'page' },
caption: t({ en: 'Early March in the pine wood above the shore: the snow goes first where '
+ 'the sun reaches the ground, weeks before the ice lets go of the lake.',
es: 'Principios de marzo en el pinar sobre la orilla: la nieve se retira primero donde el '
+ 'sol llega al suelo, semanas antes de que el hielo suelte el lago.' }),
note: t({ en: 'Photograph: Hannah Donze, CC0, via Wikimedia Commons',
es: 'Fotografía: Hannah Donze, CC0, vía Wikimedia Commons' }),
altText: t({ en: 'A walker on a snowy path between tall pines.',
es: 'Un caminante en un sendero nevado entre pinos altos.' }) },
{ id: 'ice-art', typeId: 'photo', kind: 'svg', createdAt: 0, updatedAt: 0, // drawn below
svg: { fileId: 'ice-art.svg', width: TRIM * PX, height: ART * PX },
altText: t({ en: 'A lake in section: snow, white ice, black ice and water under a low sun.',
es: 'Un lago en sección: nieve, hielo blanco, hielo negro y agua bajo un sol bajo.' }) },
];
A design element names its picture by resource id, so the opener’s photograph is declared like any figure but never cited: only the opener draws it, out to the trim, which no float reaches. Bitmaps are measured at the page’s 150 dpi, so the pine wood’s 2000 px make 339 mm and shrink to the 195 mm measure, about 260 dpi in print. The pictures get a type of their own, with an empty caption prefix and numbering template, so the pine wood’s caption carries no figure number. The band is a page-wide top float, and a top float opens the page after the one that cites it. Its ::resource line sits on the verso, after the 1944 paragraph, so the band heads the recto.
#3 · Hang the quotation mark in the margin
// The glyph is centred in an icon square that the box keeps as a column, size + gap wide,
// left of the text. A negative gap pulls the text back over the square's empty right side,
// and a left padding of −(size + gap) moves that column out into the margin, so the text
// starts on the column's edge and the mark hangs outside it. The frame stays on the column
// (a background would stop short of the mark). « sits lower and runs wider than “, so the
// Spanish mark is set smaller.
const MARK = t({ en: { glyph: '“', size: 50, column: 34 }, // pt; the column is 12 mm
es: { glyph: '«', size: 28, column: 22.5 } });
// The paddings are optical: once the next paragraph snaps to the grid, the quote has
// the same air above and below it, in both languages.
const quote = { id: 'pullquote', backgroundEnabled: false, marginTop: pt(LEAD),
marginBottom: pt(0), padding: { top: pt(8), right: pt(0), bottom: pt(7),
left: pt(-MARK.column) }, // negative: the icon column starts out in the margin
icon: { kind: 'glyph', glyph: MARK.glyph, fontFamily: 'Instrument Serif',
size: pt(MARK.size), color: col('lake') },
titleStyle: { gap: pt(MARK.column - MARK.size) }, // negative too: size + gap = column
body: { fontFamily: 'Instrument Serif', fontSize: pt(19), lineHeight: pt(1.5 * LEAD),
textAlign: 'left', hyphenation: false, color: col('lake'), // display type: no hyphens
italicColor: col('lake'), firstLineIndent: pt(0) } };
A glyph icon takes a column of its own beside the text, which would indent the quote. The negative gap slides the text back over the empty right-hand side of the glyph’s square. A negative left padding as wide as what is left of that column (size + gap, 34 pt) then moves the column out into the margin, and the text starts back on the column edge. The box’s frame stays on the column, so a background would stop short of the mark. The square starts 12 mm out, and the mark, centred in it, hangs about 6 mm into the verso’s 14 mm outer margin. The Spanish edition sets its « smaller, because a guillemet sits lower and runs wider than a quotation mark.
#4 · Float the boxes to a column head and the page foot
// Floated boxes keep one body line from the text, so they need no margins of their own.
const glance = { id: 'glance', placement: 'top', // floats to the next column head: no hole
backgroundEnabled: false, // one device, the stripe; the text keeps the column's edges
stripe: { enabled: true, side: 'top', width: pt(2.5), color: col('lake') },
padding: { top: mm(2.5), right: pt(0), bottom: pt(0), left: pt(0) },
titleStyle: { ...sans, fontWeight: 700, fontSize: pt(7.5), letterSpacing: pt(1.5),
color: col('lake'), gap: mm(2) },
body: { fontFamily: 'Instrument Sans', fontSize: pt(8.6), lineHeight: pt(12.2),
textAlign: 'left', hyphenation: false, firstLineIndent: pt(0) } }; // ink from bodyText
const numbers = { id: 'numbers', span: 'page', placement: 'bottom', // floats to a page foot
background: col('ink'), columnGap: mm(8),
padding: { top: mm(5), right: mm(6), bottom: mm(5.5), left: mm(6) },
titleStyle: { ...sans, fontWeight: 700, fontSize: pt(7.5), letterSpacing: pt(1.5),
color: col('ice'), gap: mm(1) },
body: { fontFamily: 'Instrument Sans', fontSize: pt(9), lineHeight: pt(12.5),
textAlign: 'left', hyphenation: false, color: col('ice'), firstLineIndent: pt(0) } };
// The panel's figures are level-4 headings (#### 31), a level the story never uses.
const figures = { level: 4, fontSize: pt(40), lineHeight: pt(40), color: col('ember'),
marginBottom: pt(4) };
// The end mark is a chip of one space, :chip[ ]{style="end"}: an empty box. Its lengths are
// in its own ems: paddingX makes the width, and the height is its font size's band (0.8
// ascent + 0.25 descent). It is ink, like the text it closes, in the story and in the guide.
const endMark = { id: 'end', background: col('ink'), borderWidth: pt(0), borderRadius: pt(0),
fontSize: em(0.62), paddingX: em(0.525), paddingY: em(0), gap: em(0.8) }; // 1.05 em square
With placement: 'top' the fact box floats: it leaves the flow and takes the next free column head, so the text runs on to the foot of the column instead of leaving a gap where the box did not fit. The numbers panel floats the other way, to the foot of the page, and spans both columns; its three figures are level-4 headings, a level the story never uses, placed by breaks="3,5", which counts child blocks, not lines. The end mark is a chip with no visible text. Its paddingX gives the square its width and the chip’s font size gives its height, both 1.05 em at the chip’s own size.
#5 · Running heads that name the issue and the story
const FOLIO_PT = 8.5; // the folio's size in pt
const LABEL_PT = 7.5; // the label's size in pt
const SQUARE = 2.1; // mm: the lake square's side, the folio's cap height
const label = { ...sans, fontSize: pt(LABEL_PT), letterSpacing: pt(1.3), color: col('muted') };
const folio = { fontFamily: 'Instrument Sans', fontWeight: 700, fontSize: pt(FOLIO_PT),
color: col('ink') };
// A design text's baseline sits 0.8 down its line box, 1.2 × its size (the default lineHeight).
const baseline = (size) => size * 1.2 * 0.8 * 25.4 / 72; // mm from its box's top, size in pt
const HEAD_Y = 12; // mm from the top edge to the folio's box, inside the 22 mm top margin
const LINE = HEAD_Y + baseline(FOLIO_PT); // the heads' one baseline, from the top edge
const pin = (edge, x, y = HEAD_Y) => ({ anchor: { to: 'page', edge },
offset: { x: mm(x), y: mm(y) } }); // in the margin (gotcha: header-paints-over-text)
const sides = [['even', 'left', 1], ['odd', 'right', -1]]; // 1: the outer edge is on the left
const header = { elements: sides.flatMap(([parity, edge, s]) => [
{ kind: 'text', id: `folio-${parity}`, content: '{pageNumber}', ...folio,
placement: pin(`top-${edge}`, s * OUTER) },
{ kind: 'box', id: `square-${parity}`, style: { backgroundColor: col('lake') },
placement: { ...pin(`top-${edge}`, s * (OUTER + 7.5), LINE - SQUARE), // on the line
size: { width: mm(SQUARE), height: mm(SQUARE) } } },
// The smaller label's baseline sits higher in its box (0.34 mm at 7.5 and 8.5 pt), so its
// box goes that much lower: folio, square and label share one baseline at any size.
{ kind: 'text', id: `head-${parity}`, ...label,
content: s > 0 ? '{title} · {subtitle}' : '{chapterTitle}',
placement: pin(`top-${edge}`, s * (OUTER + 11.5), LINE - baseline(LABEL_PT)) },
].map((element) => ({ ...element, parity, pages: 'body' }))) }; // no running heads on openers
const footer = { elements: sides.map(([parity, edge, s]) => ({ kind: 'text', parity,
id: `drop-folio-${parity}`, ...folio, content: '{pageNumber}', pages: 'opener', align: edge,
placement: pin(`bottom-${edge}`, s * OUTER, -11) })) }; // an opener's only folio, at the foot
Header elements paint over the page and reserve no space, so every piece is anchored to the page in the top margin with millimetre offsets. The verso names the magazine and the issue from the frontmatter, the recto the feature’s title, and pages: 'body' keeps both off the openers, which carry only a folio, at the foot. A design text’s baseline sits 0.8 of the way down its line box, which is 1.2 times its size, so baseline() drops the 7.5 pt label 0.34 mm below the 8.5 pt folio and stands the square on the same line. If you change either size, the three pieces still share one baseline.
#6 · Reuse the opener for the next item
const ART = 126; // mm: the drawing bleeds less far down the page than the photograph
// On its pages, 'lake' turns rust in the opener, the headings, the boxes and the chips.
const guide = { id: 'guide', advancedDesign: opener('ice-art', ART),
palette: { lake: palette.rust } };
The opener is a function, so the field guide gets the same design with its own picture and depth through a heading style, # Five Kinds of Ice {style="guide" kicker="Field guide" …}. The drawing bleeds 126 mm down the page instead of 160; the credit and the kicker are measured from depth - TOP and the other words hang from the kicker, so they all move up 34 mm and the guide’s text starts higher. The style’s palette maps lake to rust on those pages, so the kicker, and any crosshead or box linked to lake, turns rust without a colour argument to opener(); a chip linked to lake would turn rust as well, and the end mark is ink in both items.
The whole recipe
// ═══ Postext Cookbook · Nº 004 · Magazine feature: photo opener to end mark ═══════
// https://postext.dev/en/cookbook/magazine-feature-opener
// Code: MIT · Text: original (CC BY 4.0) · Photos: Ales Krivec, Hannah Donze (CC0)
// Fonts: Literata, Instrument Serif, Instrument Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A nature feature from a winter issue. The level-1 heading carries its kicker, standfirst,
// byline and photo credit as attributes, and one opener design lays them out under a bleed
// photograph; the story runs on with a pull quote, a fact box, a photo band, a numbers panel
// and an end mark, and the next item reuses the opener with a drawing in place of the photo.
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'magazine-feature-opener';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Every colour below is linked to this palette by id.
const palette = {
ink: '#15191c', // text: a blue-black
lake: '#2d6a7d', // the accent: kickers, crossheads, the quote, the fact box's stripe
ember: '#c8773d', // the panel's figures: 5.2:1 on ink (only 3.4:1 on paper)
rust: '#9a5a2e', // the field guide's accent, swapped in for 'lake' by its heading style
ice: '#dbe8ec', // the type on the dark panel and the drawing's sky
rule: '#c7cdd1', // the drawing's far ridge and air bubbles
muted: '#66707a', // running heads, credits, the colophon
paper: '#ffffff',
};
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: 'lake (defaults)', value: { hex: palette.lake, model: 'hex' } },
];
const TRIM = 225; // page width in mm, shared with the drawing
const INNER = 16; // inner margin in mm
const OUTER = 14; // outer margin in mm: folios and running heads align to it
const LEAD = 13.4; // body leading in pt: the baseline grid
// #region answer: a bleed photo, then the heading's kicker, headline, standfirst, byline and credit
const TOP = 22; // top margin in mm: an opener's container starts here
const sans = { fontFamily: 'Instrument Sans', fontWeight: 600, textTransform: 'uppercase' };
const HEAD = 118; // mm: the headline's measure; the standfirst takes the rest of the line
// Empty padding paints nothing but counts: the story starts on the first grid line at least
// 5 mm under the lower of the headline and the byline, however many lines each one runs to.
const air = { padding: { bottom: mm(5) } };
const at = (id, edge, x, y, width) => ({ anchor: { to: id, edge },
offset: { x: mm(x), y: mm(y) }, ...(width && { size: { width: mm(width) } }) });
const opener = (resourceId, depth) => ({ // depth: how far down the page the picture bleeds
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
#Open every item on a recto
With 'odd', the field guide moves to page 61, and page 60 stays blank.
- { level: 1, span: 'page', breakBefore: { enabled: true, parity: 'any' },
+ { level: 1, span: 'page', breakBefore: { enabled: true, parity: 'odd' },#Put the title on a band of colour
For a textbook chapter, where a colour band and a big number replace the photograph, see Chapter opener on a full-bleed band.
Pitfalls
Pitfall
Attribute values: no { or }; single-quote a value with "
An attribute value ends at the closing brace, so it cannot hold { or }. A value that contains a double quote goes in single quotes; a dollar sign is fine. Heading attributes →
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 →
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
Header and footer elements paint over text
Header and footer elements are painted over the page and the text area does not make room for them. Keep them within the margins, which are what reserve their space. Running heads and folios →
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 →
- An image element fits the picture inside its box and never crops it. Crop the JPEG to the proportions of the box, 225 × 160 mm here, or the photograph shrinks and leaves white strips at the edges of the page.
- The hanging mark needs a margin. If an edit moves the pull quote into a right-hand column, the mark fills the 6 mm gutter and touches the text of the left-hand column: move the quote a paragraph earlier or later.
- The story is fitted to end on page 59, above the numbers panel. A few more lines send its tail to a page of its own, so after an edit, fit the copy again in both languages.
runtMinCharacters: 40keeps one-word last lines out. When the line breaker cannot avoid a short last line, the engine sets the paragraph one line shorter, with tighter word spaces and, if that is not enough, up to 0.01 em less between letters. After an edit, look for a paragraph set that tight and trim or add a few words to it instead; the shipped copy needs the fix in neither language.
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Images
- Clouds mirrored in a mountain lake (the opener photograph) · Ales Krivec · CC0 1.0
- Walk in a thawing forest (the photo band) · Hannah Donze · CC0 1.0
- Fonts
- Literata (SIL OFL 1.1) · Instrument Serif (SIL OFL 1.1) · Instrument Sans (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


