In short
A seven-page instruction booklet in German for an electric kettle. It shows how to make safety warning boxes with a warning triangle, in red or amber by level of danger.
What you'll build
A seven-page instruction manual for the Verra W1, an invented electric kettle, in German on A5. The safety page sets its two hazard levels as boxes: a band in the signal colour runs down the left side and carries the warning triangle, and a thin frame of the same colour closes the box, red for WARNUNG and amber for VORSICHT. HINWEIS, the level for damage to the appliance, drops the band and the triangle for a rounded teal tint. The paragraph above the boxes sets all three signal words as filled chips. Page 3 has a parts drawing with numbered leaders above its legend, and on page 4 the key names are outlined chips beside large step numbers. The troubleshooting table runs over pages 6 and 7. Captions read Abbildung and Tabelle, and the split table is marked Fortsetzung on both pages.
This recipe answers
- How do I make note, tip or warning boxes with an icon, a coloured stripe and rounded corners?
- How do I make inline chips: keyboard keys, tags, word banks for exercises?
- How do I customise lists: bullets per level, (a)/(i) numbering, task checkboxes, spacing that stays on the grid?
- How do I add a figure with a numbered caption and cite it in the text ("see Fig. 3.2")?
- How do I make a table with header rows, merged cells, column widths and per-cell alignment?
- How do I split a long table across pages with a repeated header and a "continued" marker?
- How do I get "Figure" and "Table" labels in my document's language?
The short answer
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
{ ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];
Signal-word boxes: a band in the hazard's colour carries its triangle
Ingredients
- Features
- Box icons and corner badgesCallout boxesCustom resource typesLink addresses in printInline chipsCitations that place figuresFigures exactly hereFigure placementTables from dataTable styleTables across pagesNumbered headingsNumbered listsHyphenation and document languageFigure and Table in your languageDesigned openersHeading stylesCovers, title pages and colophonsRunning heads and foliosText, rules and boxes in page designs
- Also uses
- FootnotesHeading attributesPage and column breaksHeads by page roleParagraph stylesFigures and tables as resourcesNamed table stylesUnnumbered chapters
- Type
- Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · A band that carries the triangle
The code is the short answer above. stripe paints the band down the left edge. When a box has a side stripe, the icon is centred on the stripe instead of taking a column of its own (callout styles), and align: 'top' puts the icon's top edge level with the title's. The border in the same colour closes the band into a frame; without it the text of the box would stand on the bare page beside a coloured bar. PAD_Y is worked out so that the title, its gap and the top and bottom padding add up to two lines of the 12.8 pt grid. The body keeps the grid's leading, so each box is a whole number of lines tall (WARNUNG 10, VORSICHT 8), and marginTop: pt(LEAD) leaves exactly one line between the two boxes on page 2. VORSICHT keeps amber for the band and the frame and sets its title and bullets in ink: amber on white measures 2.0:1, and small type needs 4.5:1. HINWEIS starts from the same base (...notice(…)) and turns the band and the frame off, so its info icon takes a column of its own and borderRadius rounds a plain tint.
#2 · German names for figures and tables
const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
// The built-in types in German, Abbildung and Tabelle; a table is captioned over its head.
const resourceTypes = defaultResourceTypes('de').map((type) => ({ ...type, ...counted,
...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));
const tableStyle = { rules: 'horizontal', borderColor: col('rule'), borderWidth: pt(0.5),
headerBackground: col('ink'), headerColor: col('paper'), headerFontFamily: MONO,
headerFontSize: pt(7.6), bodyFontSize: pt(8.2), cellPadding: mm(1.3),
// The engine's own German strings are '(Forts.)' and 'Wird fortgesetzt': these spell them out.
continuedSuffix: '(Fortsetzung)', continuesMarker: 'Fortsetzung auf der nächsten Seite' };
locale: 'de' gives the manual German hyphenation and German names for the built-in types: with nothing else, the captions read Abbildung 2.1 and Tabelle 5.1, and the note under the first part of the split table says Wird fortgesetzt. The table style spells that note and the caption's suffix out, and defaultResourceTypes('de') is passed for two changes. counted is the first: {n} with resetOn: 'never' counts through the whole manual (Abbildung 1, Tabelle 1 to 3) instead of starting again in every section. Only the table type sets captionStyle.position: 'above', so tables take their caption over the head and the drawing keeps its caption underneath.
#3 · Keys, signal words and part numbers as chips
const filled = (id, fill, ink) => ({ id, fontFamily: DISPLAY, bold: true, fontSize: em(0.82),
background: col(fill), color: col(ink), borderWidth: pt(0), paddingX: em(0.45) }); // no outline
const chipStyles = [
{ id: 'taste', fontFamily: MONO, bold: true, fontSize: em(0.92), backgroundEnabled: false,
borderColor: col('ink'), borderWidth: pt(0.6), borderRadius: pt(2.2), paddingX: em(0.4) },
filled('warnung', 'warning', 'paper'), filled('vorsicht', 'caution', 'ink'),
filled('hinweis', 'brand', 'paper'), { ...filled('nr', 'brand', 'paper'), fontSize: em(0.95),
borderRadius: em(1) }, // a part number, round like the drawing's
];
taste outlines a key name in the mono face with no fill, the way the label is printed on the button. The signal-word chips are filled with the colours of their boxes, and the amber chip sets its word in ink, as the VORSICHT title does. nr gives the part numbers a radius larger than half their height, so they come out as discs like the numbered circles on the drawing. Chip sizes are set in em of the text around them: a key is 8.6 pt in the running text and 7.5 pt in a table cell (chip styles).
#4 · Step numbers on the baseline
const orderedLists = { separator: '', fontFamily: DISPLAY, fontWeight: 800, color: col('brand'),
numberFontSize: pt(15), gap: mm(3), itemSpacing: pt(5), marginTop: pt(LEAD / 2),
marginBottom: pt(0), numberVerticalOffset: pt(-1) }; // gotcha: list-number-centred
const unorderedLists = { color: col('brand'), gap: mm(2), marginTop: pt(0), marginBottom: pt(0),
levels: [{ level: 2, bulletChar: '–', indent: mm(6.5) }, // at a step's text: number + 3 mm gap
{ level: 3, bulletChar: '–', color: col('muted') }] }; // teal •, teal –, grey –
The steps are an ordered list with the numbers in Red Hat Display 800 at 15 pt, in teal, with no separator. A list number is centred on its first line, not stood on the baseline, so a 15 pt figure beside 9.3 pt text hangs about 1 pt below the line. numberVerticalOffset: pt(-1), a value measured on the capture, lifts its foot onto the baseline. itemSpacing separates the steps by 5 pt to make room for the large figures. The bullets nested under a step start at 6.5 mm, level with the step's text; they are teal dashes, and the third level has grey ones (ordered lists).
#5 · Section numbers in a reversed tab
const H1 = 14, TAB = 2 * LEAD - 3.6, PAD = (TAB - H1 * 1.2) / 2; // pt: a square 2 lines less 3.6
const face = { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(H1), lineHeight: 1.2 }; // both
const section = { level: 1, numberingTemplate: '{1}', // {number}: 1, 2, 3 …
breakBefore: { enabled: false }, marginTop: pt(LEAD), marginBottom: pt(LEAD / 2), // run on
advancedDesign: { enabled: true, slot: { elements: [
{ kind: 'text', id: 'tab', content: '{number}', ...face, color: col('paper'), align: 'center',
box: { backgroundColor: col('brand'), padding: pad(PAD) },
placement: pin('container', 'top-left', 0, 0, { width: pt(TAB) }) },
{ kind: 'text', id: 'title', content: '{titleText}', ...face, color: col('ink'),
overflow: 'wrap', box: { padding: { top: pt(PAD) } }, placement: pin('#tab', 'right-of', 3) },
] } } };
Each section is a first-level heading in the column, drawn from a design slot. The tab prints {number} (filled by numberingTemplate: '{1}') in white on a teal square, and the title starts 3 mm to its right. Number and title share one size and line height, so the same top padding sets them on one baseline. The tab is a 22 pt square, 3.6 pt less than two lines of the 12.8 pt grid, so the heading stays within two grid lines. The cover is a first-level heading too, set in an unnumbered heading style, so Sicherheitshinweise is section 1.
#6 · A troubleshooting table with merged cells that splits
function faultTable(tsv) { // the first line is the head row; the widths are weights
let m = { ...parseTSV(tsv, { headerRows: 1 }), columnWidths: [30, 34, 36] };
for (let r = 2, top = 1; r < m.rows.length; r++) { // a rowspan per fault: no cut runs through it
if (m.rows[r][0].content) top = r; // mergeCells hides what it covers: merged-cells-hiddenby
else m = mergeCells(m, { start: { row: top, col: 0 }, end: { row: r, col: 0 } });
}
return m;
}
const fold = (rows, columnWidths) => ({ columnWidths, rows: rows.slice(0, rows.length / 2) // 2 up
.map((row, k) => [...row, ...rows[k + rows.length / 2]]) });
const legend = fold(parseTSV(parts).rows.map(([chip, name]) => [{ ...chip, align: 'center' },
name]), [7, 43, 7, 43]); // each part's number chip centred in its narrow column
const HERE = { placement: { position: 'here' } }; // at the resource's ::resource line
const table = (id, caption, model, styleId = 'bare', where = HERE) => ({ id, typeId: 'table',
kind: 'table', caption, table: { model, styleId }, createdAt: 0, updatedAt: 0, ...where });
const tables = [table('legende', 'Teile des Verra W1', legend),
table('daten', 'Kenndaten des VW-170', fold(parseTSV(data).rows, [20, 30, 20, 30])),
table('stoerungen', 'Störungen und ihre Behebung', faultTable(faults), null, // the house style,
{ placement: { position: 'top' } })]; // a float: it heads the page after its citation
Each table is TSV in a content file of its own. In the troubleshooting data, a line whose first cell is empty belongs to the fault above it, and mergeCells joins those first cells into one tall cell and marks the cells it covers as hidden. parseTSV sets no header row, so headerRowCount: 1 declares it, and that row is the one repeated on page 7. The table is taller than a page, so it is cut and goes on overleaf. position: 'top' makes it a float at the head of page 6; set 'here' it would be cut the same way since postext 1.25, but the text after it would start lower on page 7 and push the last lines to an eighth page. The cut falls between rows and never through a merged cell, so every fault stays on the same page as its causes (tables taller than the page). It is cited on page 5 and heads page 6, the first page after its citation that a top float can take. fold sets two halves of a list side by side, for the legend and for the technical data, and the legend centres its number chips with align: 'center'.
#7 · A web address and a code for the reader on paper
The disposal section sends the reader to the collection-point finder of the Stiftung EAR, the German register for old appliances, with an ordinary Markdown link. On screen and in the PDF it stays a link; on paper the reader could not follow it, so links: { print: 'notes', show: 'both' } adds a note marker after the link text and sets the address at the foot of the page beside a QR code. urlDisplay: 'short' drops the https:// and the trailing slash from the printed address, and qr: { size: mm(12), side: 'start' } puts a 12 mm code before the note's line. Link notes are footnotes, so footnotes sets their size, colour and rule. The note takes three lines of page 7, so the disposal paragraph, one remedy in the table and the colophon were shortened to keep the manual on seven pages (links in print).
The whole recipe
// ═══ Postext Cookbook · Nº 050 · Product manual with safety notices ════════════════
// https://postext.dev/en/cookbook/product-manual-warnings
// Code: MIT · Text: original, in German (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1) · Needs postext ≥ 1.65.0
import {
buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage, parseTSV,
mergeCells, defaultResourceTypes, inlineSvgFonts } from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'product-manual-warnings';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1a1f24', paper: '#ffffff', // a blue-black on white
brand: '#10727b', tint: '#e4f0f1', // the house teal (5.7:1 on white) and its pale tint
warning: '#d62e1f', caution: '#f2a900', // the signal colours of WARNUNG and VORSICHT
rule: '#cfd5da', muted: '#5b6570' }; // hairlines; running heads and notes
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.brand }) // the defaults
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Red Hat Text', 'Red Hat Display', 'Red Hat Mono'];
const PAGE = { w: 148, h: 210, top: 19, bottom: 19.4, inner: 17, outer: 13 }; // mm: A5, mirrored
const LEAD = 12.8; // pt: the body's leading and baseline grid, 38 lines to the page
const pin = (to, edge, x = 0, y = 0, size) => ({ anchor: { to, edge },
offset: { x: mm(x), y: mm(y) }, ...(size && { size }) });
const pad = (y, x = 0) => ({ top: pt(y), bottom: pt(y), left: pt(x), right: pt(x) }); // pt
// #region answer: signal-word boxes: a band in the hazard's colour carries its triangle
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
{ ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];
// #endregion
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
#Number figures and tables by section
With the section number in the template and a reset at every section, the drawing becomes Abbildung 2.1 and the troubleshooting table Tabelle 5.1.
-const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
+const counted = { numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal' };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
A list number is centred on its first line, not set on the baseline
An ordered list's number is painted with the canvas 'middle' baseline, 0.3 em of the text above the item's first baseline, so a number in another face or at a larger numberFontSize grows up and down from there instead of standing on the line: a display face rides high, and a big step number hangs across the first line. Place it with orderedLists.numberVerticalOffset, and check the result at full size. Contents numbers sit on the baseline since postext 1.5; list numbers are still centred. Numbered lists →
- Column balancing pushes a box that closes a page down to the page's last grid line, so any room left on the page opens above the box (column balancing). The text of page 2 was fitted to fill its column exactly. Delete one VORSICHT bullet and the box still ends at the foot, while the gap between the two boxes grows from 4.5 to 13.6 mm; with
headings: { balancing: { enabled: false } }the box stays one line under WARNUNG and the page ends two lines short.
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Fonts
- Red Hat Text (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


