In short
A school science worksheet about building a sundial. It shows boxes that break across two columns, move to the top of the next page or stay fixed at the bottom of a page.
What you'll build
Four pages of Taller de ciencias, a Spanish school lab workbook: Práctica 4, “Construye un reloj de sol” (Build a sundial). On page 42 the safety warning stays in one piece, and the fourteen-step procedure, on a yellow fill with a compass badge on its corner, starts at the foot of the left column and goes on at the head of the right one, at the same measure and without its title. The Madrid data sheet leaves the flow on that page and heads page 43, above the text. A charcoal “Autoevaluación · 10 min” badge is pinned to the foot of the last page, with a pointing hand in the margin beside it. On the opener, a sun-yellow band carries a chart of a stick's shadows from noon to 5 p.m. at Madrid's latitude, and a panel lists the materials in three columns across the page.
This recipe answers
- How do I let a long box split across columns and pages, or keep a short one together?
- How do I float a box to the top or bottom of the page while the text keeps flowing?
- How do I pin a badge or sticker to a fixed position on the page?
- How do I set a box across both columns mid-page, such as a 3-up "in numbers" panel?
The short answer
const HAND = 6, GAP = 2, RULE = 0.75 * PT; // mm: the badge's hand, its gap, the hand's rule
const calloutStyles = [
// Kept whole: keepTogether defaults to true, so a box that does not fit the rest of a
// column moves on in one piece; only a box taller than a whole column splits anyway.
box('seguridad', bar('charcoal', 'aviso')),
// Split: the procedure fits a column, so it takes keepTogether: false to break where it
// falls instead of moving on whole: between steps, or inside one (splitMinLines, default
// 2, keeps at least two lines of the step on each side of the cut). The rest goes on in
// the next column or page without the title or the icon; a corner icon takes no room
// from the text, where an inline one would keep its column in both parts.
box('pasos', { keepTogether: false, background: col('light'),
icon: icon('compas', 7, { position: 'corner', cornerSide: 'outer' }) }),
// Floated: its fence adds placement="top", so the box leaves the flow where the fence
// stands and heads the next page, while the text after it fills this one.
box('datos', { span: 'page', background: col('tint') }),
// Pinned: 'fixed' sets the box on the page where its fence falls, at the bottom-left corner
// of the text block unless fixed.anchor says otherwise, and the column text keeps out of it.
// width: 'auto' shrink-wraps the title, so an empty fence prints a badge.
box('autoevaluacion', { placement: 'fixed', width: 'auto',
// Hang the hand and its rule in the margin (the outer one on this verso), so the badge
// itself lines up with the text: [hand][rule][GAP][badge].
fixed: { offset: { x: mm(-(HAND + RULE + GAP)) } },
marker: { ...icon('mano', HAND), gap: mm(GAP),
rule: { enabled: true, color: col('charcoal'), width: mm(RULE) } },
background: col('charcoal'), borderRadius: mm(3.2),
padding: { top: mm(1.6), right: mm(3.4), bottom: mm(1.6), left: mm(3.4) },
titleStyle: { ...TITLE, color: col('paper') } }),
// Across the page, in the flow: the text above it is cut level and resumes under it.
box('resumen', { span: 'page', backgroundEnabled: false,
stripe: { enabled: true, side: 'top', width: pt(2.5), color: col('charcoal') } }),
];
One style per behaviour: kept whole, split, floated, pinned, page-wide
Ingredients
- Features
- Boxes that split or stay wholeFloated boxesPinned boxes and badgesMarker column beside a boxBoxes across the pageColumns in a box or in the textBox icons and corner badgesCallout boxesExplicit vertical spaceCitations that place figuresFigure placementColumn balancingTables from dataNamed table stylesFigure and Table in your languageNumbered headingsDesigned openersHeading attributesRunning heads and foliosWarnings and diagnostics
- Also uses
- Figures exactly hereFull-width chapter bandHeads by page roleParagraph stylesFigures and tables as resources
- Type
- Host Grotesk, Commit Mono (SIL OFL 1.1)
- Assets
- The shadow chart, the dial in profile and the icons, drawn in code in the page's palette (Ignacio Ferro, CC BY 4.0)
Method
#1 · One base style for every box
const TITLE = { fontFamily: LABEL, fontSize: pt(8), color: col('charcoal'),
textTransform: 'uppercase', letterSpacing: pt(1.2) }; // bold by default
const BOX_TYPE = { fontSize: pt(8.8), lineHeight: pt(12.4) }; // colours inherit bodyText
const box = (id, device) => ({ id, // margins: the defaults, snapped to whole grid lines
padding: { top: mm(3), right: mm(3.6), bottom: mm(3.4), left: mm(3.6) },
titleStyle: { ...TITLE, gap: mm(2) }, body: BOX_TYPE,
lists: { gap: mm(2), itemSpacing: pt(3) }, ...device });
const icon = (id, size, extra) => ({ kind: 'resource', resourceId: id, size: mm(size),
...extra });
// A side bar with its icon centred on it, 1.4 mm narrower than the bar.
const bar = (hue, id, width = 5.6) => ({ backgroundEnabled: false,
stripe: { enabled: true, side: 'left', width: mm(width), color: col(hue) },
icon: icon(id, width - 1.4) });
Every style starts from box(): the mono title, 8.8 pt type against the text's 9.4 pt, and the padding. Each then adds one device: a charcoal bar on the safety warning, a yellow fill on the procedure, a paper tint on the data sheet, a top rule on the summary, a charcoal pill for the badge. A student can tell the boxes apart by that device before reading a title. On the procedure the fill also marks the continuation: the part at the head of the right column has no title, so only the yellow links it to steps 1 to 4 at the foot of the left one.
#2 · Keep, split, float and pin
The code is the short answer above. The procedure measures 192 mm and a column holds 211, so a box kept whole would jump to the head of the right column and leave 43 mm empty at the foot of the left one. keepTogether: false lets it start where it falls and go on in the next column, or on the next page, as the second variation shows (the :::callout container). A continuation drops the title and the icon. An inline icon would take a column of its own from the steps in both parts, so the compass sits on the box's outer corner, where it takes no width. The data sheet's fence carries placement="top", so the box leaves the flow on page 42 and heads the next page. The badge is fixed, and a negative offset.x moves the hand and its rule into the outer margin, so the left edge of the badge lines up with the text.
#3 · Cross the page with a three-column panel
const materials = box('material', { span: 'page', background: col('sun'),
marginBottom: pt(LEAD), // one more grid line of air before the text resumes
padding: { top: mm(3.6), right: mm(4.4), bottom: mm(3.8), left: mm(4.4) },
columnGap: mm(GUTTER), // the page's gutter: the panel's columns sit as far apart as the text's
body: { ...BOX_TYPE, paragraphSpacing: false },
lists: { color: col('ink'), gap: mm(1.8), itemSpacing: pt(1) } });
With span: 'page' the materials box crosses both columns. The introduction above it is cut level, and the text resumes in two columns under it (page 41). Inside the fence, :::columns{count=3 breaks="5,9"} sets where each column starts instead of balancing them. breaks counts child blocks, and each list item is one, so the second and third columns open at the fifth and ninth blocks, the bold labels. columnGap is the page's 7 mm gutter, so the panel's columns sit as far apart as the text columns.
:::callout{type="material" title="Necesitarás"}
:::columns{count=3 breaks="5,9"}
**Para la esfera**
- Cartón pluma de 20 × 30 cm
- La plantilla de la esfera
- Pegamento y rotulador
**Para el gnomon y la base**
…
:::
:::#4 · One yellow for fields, a lighter one for the long box
const palette = {
ink: '#1b2430', // text
charcoal: '#2b2d42', // the safety bar, the summary's rule, the table head, the badge, titles
sun: '#f2b705', // the opener band and the materials panel: fields, never type
light: '#fad65a', // the procedure
tint: '#fff6d6', // the data sheet
rule: '#d7dde3', // hairlines
muted: '#5d6b78', // running heads, notes
paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at charcoal, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.charcoal })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
Sun yellow is kept for the fields of colour, the band and the panel, where charcoal and ink read at 7.4:1 and 8.6:1. As a type colour on white it would reach 1.8:1, so it never carries type. The procedure takes light, a paler yellow: ink reads on it at 11:1, and the break still shows in the gallery thumbnail. The data sheet takes tint, closer to paper, so it cannot be mistaken for the procedure, the other filled box on the spread. main-color points at charcoal, so the defaults the config does not override print in charcoal instead of the engine's blue.
#5 · Open on a yellow band
const BAND = 100; // mm from the trim to the foot of the band
const ART_W = 80; // mm: the width of the band's drawing, at the fore-edge
const AIR = 8; // mm between the band and the first line of text
const [TITLE_W, LEAD_W] = [104, 88]; // mm: the title's and the lead's measure
const onBand = { color: col('charcoal'), align: 'left' }; // a long title or lead wraps
const below = (id, y, width) => ({ anchor: { to: `#${id}`, edge: 'below' },
offset: { y: mm(y) }, size: { width: mm(width) } });
const opener = { enabled: true, minHeight: mm(BAND - TOP + AIR), slot: { elements: [
{ kind: 'box', id: 'band', style: { backgroundColor: col('sun') },
placement: { anchor: { to: 'page', edge: 'top-left' }, size: { height: mm(BAND) } } },
{ kind: 'image', id: 'art', resourceId: 'sombras', placement: { anchor: { to: 'page',
edge: 'top-right' }, size: { width: mm(ART_W), height: mm(BAND) } } },
{ kind: 'text', id: 'kicker', content: '{attr.kicker}', ...onBand, fontFamily: LABEL,
fontSize: pt(8.5), fontWeight: 700, letterSpacing: pt(1.7), textTransform: 'uppercase',
placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(4) } } },
{ kind: 'text', id: 'title', content: '{titleText}', ...onBand, fontFamily: TEXT,
fontSize: pt(44), fontWeight: 800, lineHeight: 0.98, placement: below('kicker', 3, TITLE_W) },
{ kind: 'text', id: 'lead', content: '{attr.lead}', ...onBand, fontFamily: TEXT,
fontSize: pt(10.5), lineHeight: 1.4, placement: below('title', 5, LEAD_W) },
{ kind: 'text', id: 'meta', content: '{attr.meta}', ...onBand, fontFamily: LABEL,
fontSize: pt(7.4), fontWeight: 700, letterSpacing: pt(1.1), textTransform: 'uppercase',
placement: below('lead', 4, LEAD_W) },
] } };
The band is a box element anchored to the page and the drawing an image element at the fore-edge; the kicker, the lead and the session line come from attributes on the heading line. Because the band is anchored to the page, the opener already reserves its height down to the band's foot, and the text would start 3.6 mm under it. minHeight: BAND - TOP + AIR asks for 8 mm; the reservation snaps to the next grid line, and the text starts 8.4 mm under the band.
The whole recipe
// ═══ Postext Cookbook · Nº 021 · Boxes that split, float and pin ══════════════════
// https://postext.dev/en/cookbook/boxes-split-float-pin
// Code: MIT · Text: original (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Host Grotesk, Commit Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// Four pages of a school lab workbook in Spanish, and five ways a box can sit on them.
import {
buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
const LANG = 'es'; // @lang: the language of the sample document (this recipe is Spanish only)
const RECIPE = 'boxes-split-float-pin';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: one yellow for fields, paler ones for two boxes, near-blacks for type and bars
const palette = {
ink: '#1b2430', // text
charcoal: '#2b2d42', // the safety bar, the summary's rule, the table head, the badge, titles
sun: '#f2b705', // the opener band and the materials panel: fields, never type
light: '#fad65a', // the procedure
tint: '#fff6d6', // the data sheet
rule: '#d7dde3', // hairlines
muted: '#5d6b78', // running heads, notes
paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at charcoal, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.charcoal })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Host Grotesk'; // text and display
const LABEL = 'Commit Mono'; // labels: kickers, box titles, step numbers, heads, the table
const LEAD = 13.6; // pt: the body leading, the pitch of the baseline grid
const LINES = 44; // grid lines in a full column
const [TRIM_W, TRIM_H, TOP, INNER, OUTER, GUTTER] = [195, 255, 22, 18, 14, 7]; // mm
const PT = 25.4 / 72; // mm in a point
// #region look: the base of every box (a mono title, smaller type), then one device each
const TITLE = { fontFamily: LABEL, fontSize: pt(8), color: col('charcoal'),
textTransform: 'uppercase', letterSpacing: pt(1.2) }; // bold by default
const BOX_TYPE = { fontSize: pt(8.8), lineHeight: pt(12.4) }; // colours inherit bodyText
const box = (id, device) => ({ id, // margins: the defaults, snapped to whole grid lines
padding: { top: mm(3), right: mm(3.6), bottom: mm(3.4), left: mm(3.6) },
titleStyle: { ...TITLE, gap: mm(2) }, body: BOX_TYPE,
lists: { gap: mm(2), itemSpacing: pt(3) }, ...device });
const icon = (id, size, extra) => ({ kind: 'resource', resourceId: id, size: mm(size),
...extra });
// A side bar with its icon centred on it, 1.4 mm narrower than the bar.
const bar = (hue, id, width = 5.6) => ({ backgroundEnabled: false,
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 the procedure in one piece
Without the setting, the procedure, which fits in a column, moves whole to the head of the right column and leaves 43 mm empty at the foot of the left one.
- box('pasos', { keepTogether: false, background: col('light'),
+ box('pasos', { background: col('light'),#Float the data sheet to the foot
With placement="bottom" in content.es.md, the data sheet takes the foot of page 42, where its fence falls. The procedure it displaces starts at the head of the right column and splits across the page turn, ending at the head of page 43.
-:::callout{type="datos" placement="top" title="Hoja de datos · Madrid, 40,4° N · 3,7° O"}
+:::callout{type="datos" placement="bottom" title="Hoja de datos · Madrid, 40,4° N · 3,7° O"}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
Page 1 is a recto: plan pages with physical numbers
Page 1 is a right-hand page and page 2 the first verso, so plan spreads with physical page numbers: an opener on an even page faces the odd page after it. Page and column breaks →
Layout warning · calloutOverflow
Callout overflows its column
Why. A box that no cut can split (a figure, a table or a box nested inside it taller than the column, or too high splitMinLines) was placed overflowing; the engine records it in doc.warnings and the Sandbox lists it. A span: 'side' box taller than an empty side column is placed overflowing too.
Fix. Shorten the box, let it split with keepTogether: false, lower splitMinLines, or give it another span. Docs →
- A box taller than a whole column splits whatever
keepTogethersays. The setting only decides for boxes that fit a column, like this 192 mm procedure in a 211 mm column. splitMinLines(2 by default) is the fewest lines a cut leaves on each side of it, counted in the step it cuts, so no step leaves a line alone. The text before the procedure is fitted so the cut falls between steps 4 and 5. Any edit to the text above a split box can move the cut, so look at where it falls after each one.- An inline icon takes a column of its own, and a continuation keeps that column, empty: the steps lose the icon's width in both parts. A corner icon, or a side stripe for the icon to sit on, leaves them the full measure.
- A box floated with
placement="top"heads the page after the one its fence falls on, so the fence goes on the page before the one the box should head. Here it sits just before the procedure, on page 42.
Credits
- Recipe
- Ignacio Ferro
- Text
- The solar-noon table: computed for Madrid with NOAA's solar equations · NOAA Global Monitoring Laboratory · public domain
- Images
- The shadow chart, the dial in profile and the icons, drawn in code in the page's palette · Ignacio Ferro · CC BY 4.0
- Fonts
- Host Grotesk (SIL OFL 1.1) · Commit Mono (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


