In short
Tell the layout which part of each photo must always show. When a column comes up a few lines short, the photo gets taller instead of leaving a gap.
What you'll build
Three pages of a coastal magazine: a feature on the trades of an estuary town, with a bleed photo across the opener and five photos in the columns. The pen sets the feature twice from the same text. In the first setting the photos keep the shape of their files, and on page 2 both columns end a line short of the grid: the left one under its last paragraph, the right one above the photo at its foot. In the second each photo names the part of the frame that must always show, and the engine crops outside it: on the same page the shellfish gatherer and the net mender each grow by a line, and both columns end on the last line of the grid. Nobody had to choose the crops.
This recipe answers
- How do I let a photo be cropped to fill a short column while its subject always stays in view?
- How do I get flush column bottoms and a balanced last page (vertical justification)?
- How do I control where a figure goes: top of page, across both columns, exactly here, or in the margin?
The short answer
// Each photo names the rectangle that must always show, in fractions of the file:
// x and width of its width, y and height of its height. Outside it the engine may crop,
// so the photo can stand taller (sides cut, down to the area's width) or lower (top and
// bottom cut, down to its height) than the file, always as wide as its column.
const SAFE_AREAS = {
mariscadora: { x: 0.2, y: 0.36, width: 0.34, height: 0.46 }, // Carmen, her rake and basket
redeira: { x: 0.34, y: 0.14, width: 0.4, height: 0.66 }, // Rosa and the net in her lap
carpintero: { x: 0.12, y: 0.2, width: 0.64, height: 0.62 }, // Manuel and the whole hull
faro: { x: 0.34, y: 0.14, width: 0.32, height: 0.56 }, // the tower and the walker below it
pulpeira: { x: 0.2, y: 0.08, width: 0.56, height: 0.82 }, // Lucía, the octopus, the cauldron
};
// Columns end flush on this grid by whole lines. A heading or a photo that does not fit a
// column's foot leaves lines empty there; these settings forbid the usual fixes (space above
// a heading, under a photo, or a paragraph run long), so only a photo with a safe area can
// take them, by growing a line at a time. Without safe areas the short columns stay short.
const balancing = { enabled: true, maxLinesPerHeading: 0, stretchAfterLists: false,
stretchAfterFloats: false, looseParagraphs: false };
A safe area per photo, and balancing that may only grow pictures
Ingredients
- Features
- Picture safe areaColumn balancingFigure placementFigures and tables as resourcesCitations that place figuresFigures exactly hereCaption styleCustom resource typesDesigned openersPictures in page designsHeading attributesOne or two columnsMirrored marginsRunning heads and foliosHeads by page roleSemantic colour paletteParagraph stylesPages on a canvasPDF export
- Type
- Newsreader, Archivo, Archivo Narrow (SIL OFL 1.1)
- Assets
carpintero-1600.jpgestuario-1700.jpgfaro-1600.jpgmariscadora-1600.jpgpulpeira-1600.jpgredeira-1600.jpg- The estuary at low water at dawn, with shellfish gatherers (Generated With Diffusion Models, original)
- A shellfish gatherer kneeling on the wet sand (Generated With Diffusion Models, original)
- A net mender on the quay (Generated With Diffusion Models, original)
- A shipwright planing a wooden boat in his shed (Generated With Diffusion Models, original)
- A lighthouse on a granite point and a walker below it (Generated With Diffusion Models, original)
- A cook lifting an octopus from a copper cauldron at a market (Generated With Diffusion Models, original)
Method
#1 · Mark what must stay, nothing else
The code is the short answer above. A safe area is four fractions of the picture, measured from its top-left corner. The engine may show the photo at any shape between the whole file and that rectangle, as wide as its column: taller by cutting the sides, lower by cutting the top and bottom. What lies outside the area goes in proportion to the margins on each side, so Rosa, right of centre on the quay, stays right of centre when the sides are cut.
#2 · Let balancing take the slack only through the photos
The same region sets the balancer. Its usual levers add white: a line above a heading, air under a photo, a paragraph run one line long. Here they are off, so the plain setting shows every short column as it is. A photo with a safe area is tried first anyway, before any of those levers, because a taller photo leaves no hole in the text.
#3 · The safe area belongs to the resource
const FILES = { estuario: [1700, 1133] }; // px, declared as they are; the rest 1600 × 1067
// Caption and alt text of each photo, one block per photo: content.figures.<lang>.md.
const figureTexts = String.raw`mariscadora
Carmen Lago sorts cockles on her plot of the estuary at low water.
A woman in green boots kneels on wet sand beside a rake and a mesh basket.
redeira
Rosa Doval mends a purse-seine panel on the quay.
A woman on a stool sews a green net spread around her; fishing boats behind.
carpintero
Manuel Barreiro planes the planking of the gamela.
An old man planes the side of a half-built wooden boat inside a shed.
faro
Arnela point: the lighthouse and the coastal path.
A white lighthouse on granite rocks; a walker with a red backpack below it.
pulpeira
Lucía Fraga lifts an octopus out of the copper cauldron.
A woman in an apron lifts a boiled octopus from a steaming copper pot.
`;
const CAPTIONS = Object.fromEntries(figureTexts.trim().split(/\n\s*\n/)
.map((block) => block.split('\n').map((line) => line.trim()))
.map(([id, caption, alt]) => [id, [caption, alt]]));
const PLACEMENT = { pulpeira: { position: 'here' } }; // the rest float to the first free slot
const photo = (id, safe) => {
const [w, h] = FILES[id] ?? [1600, 1067];
const [caption, alt] = CAPTIONS[id] ?? [];
return { id, typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
bitmap: { fileId: `${id}-${w}.jpg`, format: 'jpeg', width: w, height: h },
...(caption && { caption, altText: alt, placement: PLACEMENT[id] ?? { position: 'auto' } }),
...(safe && SAFE_AREAS[id] && { safeArea: SAFE_AREAS[id] }) };
};
const resources = (safe) => ['estuario', ...Object.keys(CAPTIONS)].map((id) => photo(id, safe));
safeArea sits on the resource next to its file, caption and placement, so a photo keeps it wherever it floats and in every document that uses it. The pen passes it or leaves it out, and that is the only difference between the two settings. The opener's estuary is drawn by the heading style, not floated, so it needs none.
#4 · Build both and compare
const build = (safe) => buildDocumentWithFonts({ markdown, resources: resources(safe) }, config(),
kitFonts(FONTS));
const docs = { plain: await build(false), safe: await build(true) };
Both documents come from one config and one Markdown string. Only the pages that flow on are filled to the foot: page 3 closes the feature, and a closing page only has its columns end level with each other, which here they already do, so no photo grows there. The PDF button builds whichever setting is on the desk, and the PDF clips each photo to its frame in the same way.
The whole recipe
// ═══ Postext Cookbook · Nº 116 · Photos that grow to fill a short column ═══════════
// https://postext.dev/en/cookbook/photos-fill-short-columns
// Code: MIT · Text: original (CC BY 4.0) · Photos: diffusion models
// Fonts: Newsreader, Archivo, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.25.0
//
// A magazine feature set twice. Without safe areas some columns end short; with them the
// engine crops each photo outside its area to set it taller, and the photos fill those lines.
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, defaultResourceTypes,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'en'; // @lang: the language of the sample document ('es' | 'en')
const RECIPE = 'photos-fill-short-columns';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: six named colours, the accents taken from the photos: sea slate, net green
const palette = {
ink: '#1d2326', // text: a cold near-black
sea: '#2f5d73', // the accent: kicker, caption labels, folios, references
net: '#3f6b55', // the second colour: the opener's rule
rule: '#c9d1d3', // hairlines
muted: '#5f6a6e', // 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': pointed at the accent, no default blue shows.
{ id: 'main-color', name: 'sea (defaults)', value: { hex: palette.sea, model: 'hex' } },
];
// #endregion
const [TEXT, DISPLAY, LABEL] = ['Newsreader', 'Archivo', 'Archivo Narrow'];
const LEAD = 13.6; // body leading in pt: the grid the photos grow by
const [PAGE_W, PAGE_H, TOP, BOTTOM, INNER, OUTER, GUTTER] = [225, 297, 22, 22, 18, 16, 7]; // mm
const PHOTO_H = 150; // the opener's bleed photo: 225 × 150 mm, the shape of the file
const at = (to, edge, x, y, size) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) },
...(size && { size }) });
const text = (id, content, family, size, color, placement, extra) => ({ kind: 'text', id,
content, fontFamily: family, fontSize: pt(size), color: col(color), placement,
align: 'left', overflow: 'wrap', ...extra }); // the running heads ask for an ellipsis instead
const caps = (size) => ({ fontWeight: 700, textTransform: 'uppercase',
letterSpacing: pt(size * 0.18) });
// #region answer: a safe area per photo, and balancing that may only grow pictures
// Each photo names the rectangle that must always show, in fractions of the file:
// x and width of its width, y and height of its height. Outside it the engine may crop,
// so the photo can stand taller (sides cut, down to the area's width) or lower (top and
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
#Keep an inline photo with its text
A photo set with position: 'here' and a safe area is cropped from the top and bottom when it is a little too tall for the room left in its column, instead of moving to the next one.
-const PLACEMENT = { pulpeira: { position: 'here' } }; // the rest float to the first free slot
+const PLACEMENT = { pulpeira: { position: 'here' }, faro: { position: 'here' } };#Give the balancer its other levers back
With the defaults the photos still go first, and the headings and floats take what a photo's safe area cannot.
-const balancing = { enabled: true, maxLinesPerHeading: 0, stretchAfterLists: false,
- stretchAfterFloats: false, looseParagraphs: false };
+const balancing = { enabled: true };Pitfalls
- A safe area that covers the whole picture, or one with a side under 2 % of it, is ignored: the photo is shown whole, as without one.
- Only column floats and inline photos grow. A photo floated across both columns keeps its shape, because growing it would push every column under it at once.
Credits
- Recipe
- Ignacio Ferro
- Text
- The feature, the captions and the colophon, in Spanish and English; Arnela and its people are imaginary · Postext Cookbook · CC BY 4.0
- Images
- The estuary at low water at dawn, with shellfish gatherers · Generated With Diffusion Models · original
- A shellfish gatherer kneeling on the wet sand · Generated With Diffusion Models · original
- A net mender on the quay · Generated With Diffusion Models · original
- A shipwright planing a wooden boat in his shed · Generated With Diffusion Models · original
- A lighthouse on a granite point and a walker below it · Generated With Diffusion Models · original
- A cook lifting an octopus from a copper cauldron at a market · Generated With Diffusion Models · original
- Fonts
- Newsreader (SIL OFL 1.1) · Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


