In short
A chapter from a field manual for trail workers, about draining water off paths. It shows how to give headings seven levels, each with its own look, so readers see how the parts fit together.
What you'll build
Chapter 1 of a trail crew's field manual, Drainage, on three B5 pages in two columns: IBM Plex Serif for the text, IBM Plex Sans Condensed for the heads and section numbers, IBM Plex Mono for labels, folios and subsection numbers. The opener sets the chapter number in a large amber pill over a trail's elevation profile, where amber dots mark twelve sites flagged for new water bars. Smaller pills number sections 1.1 to 1.12 and widen at 1.10. Heads 1.2.1, 1.5.1 and 1.5.2 are tracked capitals under a green rule. Levels 4 to 6 go unnumbered and change face instead (serif italic, green condensed bold, mono capitals), and a seventh level in grey italic names the tools. The safety rules open on green run-in terms. An unnumbered checklist, marked by a hollow square, closes the chapter with lists numbered 1., a) and i. and two task boxes.
This recipe answers
- How do I number headings (1, 1.1, 1.1.1) and style each level differently?
- How do I build a number badge beside the title that widens when the number grows (9 → 10)?
- How do I handle more than six heading levels?
- How do I customise lists: bullets per level, (a)/(i) numbering, task checkboxes, spacing that stays on the grid?
The short answer
const H2 = 13.5; // pt: the number and the title share one size and one line height,
const LH = 1.2; // so, under the same top padding, they share one baseline
// Every section head starts on a grid line, so the 3 pt the pill falls short of two lines
// is the gap the grid snap leaves between the pill and the text under it.
const PILL_H = 2 * LEAD - 3, PAD = (PILL_H - H2 * LH) / 2; // pt
const face = { fontFamily: DISPLAY, fontWeight: 700, fontSize: pt(H2), lineHeight: LH };
const pill = { kind: 'text', id: 'pill', content: '{number}', ...face, color: col('ink'),
box: { backgroundColor: col('signal'), borderRadius: mm(3), // no width: the pill is its
padding: { top: pt(PAD), bottom: pt(PAD), left: mm(1.8), right: mm(1.8) } }, // number
placement: at('container', 'top-left') }; // plus its padding
// 'right-of' hangs the title on the pill's right edge and aligns its lines left, so a long
// title wraps beside the number, never under it.
const sectionTitle = (from) => ({ kind: 'text', id: 'title', content: '{titleText}', ...face,
color: col('ink'), overflow: 'wrap', box: { padding: { top: pt(PAD) } },
placement: at(`#${from}`, 'right-of', mm(2.2)) });
// The H1 counter, a point, the H2 counter: 1.1 … 1.12 in the pill. h2 joins headings.levels.
const h2 = { level: 2, numberingTemplate: '{1}.{2}',
advancedDesign: { enabled: true, slot: { elements: [pill, sectionTitle('pill')] } } };
Section numbers 1.1 … 1.12 in an amber pill that widens with the number
Ingredients
- Features
- Numbered headingsText, rules and boxes in page designsAnchoring design elementsHeading levelsHeading stylesUnnumbered chaptersDesigned openersPictures in page designsHeading attributesParagraph stylesBold, italic and their coloursBullet lists and checklistsNumbered listsBaseline gridWidows, orphans and runtsRunning heads and foliosHeads by page roleMirrored marginsSemantic colour paletteFigures and tables as resources
- Also uses
- Full-width chapter band
- Type
- IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · Put the number in a pill that grows with it
The code is in the short answer above. numberingTemplate: '{1}.{2}' joins the chapter and section counters into 1.1 to 1.12 (per-level overrides). A level with an advanced design no longer prints the number before its title, so the design places {number} itself. Here it sits in a text element with a filled, rounded box and no width, so the pill is as wide as the number plus its padding: 10.1 mm for 1.9 and 12.7 mm for 1.10. 'right-of' hangs the title on the pill's right edge and aligns its lines left, which is why the long title of 1.5 wraps beside the number (element placement). The pill is 3 pt shorter than two grid lines, and every section head starts on a grid line, so those 3 pt are the gap between the pill and the text under it, whether the head opens a column or follows a paragraph.

#2 · Rule and track the third level
// A rule, a mono number and a tracked title: three elements, so this head is a design.
const small = { fontSize: pt(8.4), lineHeight: LH };
const DROP = 6; // pt: the rule drops this far toward the number, which keeps its grid line
const h3 = { level: 3, numberingTemplate: '{1}.{2}.{3}', // 1.5.1: restarts under every H2
advancedDesign: { enabled: true, slot: { elements: [
{ kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.75), color: col('band'),
placement: { ...at('container', 'top-left', mm(0), pt(DROP)), size: { width: 'fill' } } },
{ kind: 'text', id: 'num', content: '{number}', fontFamily: LABEL, fontWeight: 500, ...small,
color: col('band'), placement: at('#rule', 'below', mm(0), pt(LEAD - DROP)) },
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 600,
...small, letterSpacing: pt(1.35), textTransform: 'uppercase', color: col('ink'),
overflow: 'wrap', placement: at('#num', 'right-of', mm(2)) },
] } } };
Level 3 is drawn by a design as well: a 0.75 pt green rule, the number in IBM Plex Mono and the tracked title beside it. The third counter of '{1}.{2}.{3}' restarts under every section, so 1.2.1 and 1.5.1 both end in 1. DROP lowers only the rule. The number is placed LEAD - DROP under it, which keeps number and title a grid line below the top of the head for any DROP. With the rule nearer the number than the paragraph above, it reads as part of the head.
#3 · Step down through levels 4 to 6
const headings = { fontFamily: DISPLAY, color: col('ink'), // every head sits on the grid,
lineHeight: pt(LEAD), marginTop: pt(LEAD), marginBottom: pt(0), // a line above, none below
levels: [
// Each chapter opens on a recto.
{ level: 1, span: 'page', breakBefore: { enabled: true, parity: 'odd' },
numberingTemplate: '{1}', advancedDesign: opener },
h2, h3,
// No template below level 3, so no number: each level changes face, colour or case.
{ level: 4, fontFamily: 'IBM Plex Serif', fontWeight: 400, italic: true, fontSize: pt(11) },
{ level: 5, fontSize: pt(9.4), color: col('band') },
{ level: 6, fontFamily: LABEL, fontWeight: 600, fontSize: pt(7.8), textTransform: 'uppercase' },
] };
A level without a numberingTemplate prints no number, so from level 4 down the heads differ in face, colour or case instead: an italic serif at level 4, the display face in green at 5 and semibold mono capitals at 6. The line height and margins set on headings itself reach every level and put each head on the grid, with a blank line above it and none below. Level 1 opens each chapter on a recto, with parity: 'odd'.
#4 · Make a seventh level and an unnumbered section with styles
const headingStyles = [
// Markdown stops at ######: '###### Rock bar {style="level7"}' stays level 6 in the
// outline and is set in lower case, lighter and grey.
{ id: 'level7', fontFamily: DISPLAY, fontWeight: 500, italic: true, fontSize: pt(8.4),
textTransform: 'none', color: col('muted') },
// numbered: false: no number, and the H2 counter does not move. An empty {number} would
// still paint the amber pill, so the style draws a hollow square in its place.
{ id: 'checklist', numbered: false, advancedDesign: { enabled: true, slot: { elements: [
{ kind: 'box', id: 'box', style: { borderColor: col('signal'), borderWidth: pt(1.8),
borderRadius: mm(1.5) }, placement: { ...at('container', 'top-left'),
size: { width: pt(PILL_H), height: pt(PILL_H) } } },
sectionTitle('box'),
] } } },
];
const paragraphStyles = [
// Run-in heads: the bold term opening each rule prints in the accent, not in body ink.
{ id: 'rules', boldColor: col('band'), firstLineIndent: pt(0) },
{ id: 'colophon', fontFamily: LABEL, fontSize: pt(6.8), lineHeight: pt(9),
color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(LEAD) },
];
Markdown stops at ######, and ###### *Rock bar* would be one more level 6, only in italics. The heading style 'level7' sets the tool names in a grey condensed italic of weight 500, lighter than the 600 of level 6, and textTransform: 'none' switches off the capitals they would otherwise inherit. They read a step below the mono label above them, though at 8.4 pt they are larger than its 7.8 pt (heading styles). numbered: false leaves the checklist out of the count, so a section after it would still be 1.13. An empty {number} would still paint the amber pill, so the style brings its own design, with a hollow square in the pill's place. The green run-in terms of the safety rules come from the boldColor of a paragraph style.
#5 · Change the list markers with depth
// Zero margins keep lists on the grid; a '- [ ]' item's bullet becomes taskCheckboxChar, '☐'.
const unorderedLists = { gap: mm(2), marginTop: pt(0), marginBottom: pt(0), color: col('band'),
levels: [{ level: 2, bulletChar: '–', color: col('sage') }] }; // '•' stays at level 1
// Level 1 keeps the defaults: 'arabic' and a full stop.
const orderedLists = { fontFamily: DISPLAY, color: col('band'), gap: mm(1.6),
marginTop: pt(0), marginBottom: pt(0), levels: [
{ level: 2, numberFormat: 'lower-alpha', separator: ')' },
{ level: 3, numberFormat: 'lower-roman', color: col('muted') }] };
Each depth takes its own marker, colour and separator from levels: the checklist counts 1., a) and i. (ordered per-level overrides) and the bullets fade from green to sage (unordered per-level overrides). Level 1 keeps the default format, 'arabic'. The two - [ ] items that close the checklist print taskCheckboxChar, ☐ by default, in place of the bullet, in the green of the first-level bullets (task list extensions). With zero margins above and below, every list stays on the baseline grid.
#6 · Open the chapter on the trail's profile
const DEPTH = 96; // mm: the profile's foot, measured from the top of the page
const CLEAR = 6; // mm: the least room between the profile's foot and the text under it
const LEGEND = 7; // mm: how far the legend's top sits above the profile's foot
const big = { ...face, fontSize: pt(54), lineHeight: 1, color: col('ink') };
// The opener reserves height down to the profile's foot; minHeight reaches CLEAR mm past
// it, so the text starts on the first grid line CLEAR mm or more under the picture.
const opener = { enabled: true, minHeight: mm(DEPTH - TOP + CLEAR), slot: { elements: [
{ kind: 'image', id: 'profile', resourceId: 'profile',
placement: { ...at('page', 'top-left'), size: { width: 'fill' } } },
{ kind: 'text', id: 'num', content: '{number}', ...big, box: { backgroundColor: col('signal'),
borderRadius: mm(4), padding: { top: pt(4), bottom: pt(4), left: mm(4), right: mm(4) } },
placement: at('container', 'top-left') },
{ kind: 'text', id: 'title', content: '{titleText}', ...big, box: { padding: { top: pt(4) } },
placement: at('#num', 'right-of', mm(4)) },
{ kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: 'IBM Plex Serif', italic: true,
fontSize: pt(11.5), lineHeight: 1.3, color: col('ink'), align: 'left', overflow: 'wrap',
placement: { ...at('#num', 'below', mm(0), mm(5)), size: { width: mm(100) } } },
// The legend is design text over the picture: each edition words it in its heading.
{ kind: 'text', id: 'legend', content: '{attr.profile}', fontFamily: LABEL, fontWeight: 500,
fontSize: pt(7), color: col('tint'), placement: at('page', 'top-right', mm(-OUTER),
mm(DEPTH - LEGEND)) },
] } };
The profile is an image element of the opener, anchored to the page and as wide as it. A page-wide figure floated to the top and cited on page 1 would have opened page 2 instead (image elements). The opener reserves height down to the picture's foot, and minHeight reaches 6 mm past it, so the text starts on the first grid line 6 mm or more below the profile. The legend on the green is design text, filled from the heading's profile attribute. The large pill reuses the section pill's face and fill, and {number} prints the chapter's own number, from numberingTemplate: '{1}'.
The whole recipe
// ═══ Postext Cookbook · Nº 018 · Section heads seven levels deep ═════════════════
// https://postext.dev/en/cookbook/section-heads-field-manual
// Code: MIT · Text: original (CC BY 4.0) · Picture: drawn in code (MIT)
// Fonts: IBM Plex Serif, Sans Condensed, Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'section-heads-field-manual';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // forest green for structure, a signal amber for numbers
ink: '#1d2320', // text: a green-black
band: '#2f6b3f', // the accent: rules, run-in terms, bullets, numbers, folios (6.4:1)
signal: '#e0a526', // the number pills, with ink on them (7.3:1)
sage: '#7a9e80', // the second bullet and the profile's upper contours
tint: '#e9f0e6', // the opener's sky; the legend on the green (5.5:1)
muted: '#5f6a62', // running heads, level 7, roman list numbers, the colophon (5.6:1)
};
// col(id): a colour linked to its palette entry, in text styles and design slots alike.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// Defaults this config does not restate link to 'main-color', so it points at the accent.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.band })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const TRIM = { width: 176, height: 250 }; // mm: ISO B5, a common size for field manuals
const [TOP, INNER, OUTER] = [22, 16, 14]; // mm: margins; the running heads align to OUTER
const LEAD = 13.2; // pt: the body leading, the pitch of the baseline grid
const LINES = 44; // grid lines in the text block, so every full column ends on one baseline
const [DISPLAY, LABEL] = ['IBM Plex Sans Condensed', 'IBM Plex Mono']; // with the serif text
const at = (to, edge, x, y) => ({ anchor: { to, edge }, offset: { x, y } });
// #region answer: section numbers 1.1 … 1.12 in an amber pill that widens with the number
const H2 = 13.5; // pt: the number and the title share one size and one line height,
const LH = 1.2; // so, under the same top padding, they share one baseline
// Every section head starts on a grid line, so the 3 pt the pill falls short of two lines
// is the gap the grid snap leaves between the pill and the text under it.
const PILL_H = 2 * LEAD - 3, PAD = (PILL_H - H2 * LH) / 2; // pt
const face = { fontFamily: DISPLAY, fontWeight: 700, fontSize: pt(H2), lineHeight: LH };
const pill = { kind: 'text', id: 'pill', content: '{number}', ...face, color: col('ink'),
box: { backgroundColor: col('signal'), borderRadius: mm(3), // no width: the pill is its
padding: { top: pt(PAD), bottom: pt(PAD), left: mm(1.8), right: mm(1.8) } }, // number
placement: at('container', 'top-left') }; // plus its padding
// 'right-of' hangs the title on the pill's right edge and aligns its lines left, so a long
// title wraps beside the number, never under it.
const sectionTitle = (from) => ({ kind: 'text', id: 'title', content: '{titleText}', ...face,
color: col('ink'), overflow: 'wrap', box: { padding: { top: pt(PAD) } },
placement: at(`#${from}`, 'right-of', mm(2.2)) });
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
#Drop the chapter number from the pills
Take the chapter's counter out of the template and the pills read 1 to 12, widening at 10; level 3 prints 1.5.1 until its own template drops {1} too.
-const h2 = { level: 2, numberingTemplate: '{1}.{2}',
+const h2 = { level: 2, numberingTemplate: '{2}',#Give every pill the same width
A fixed width, that of 1.10, centres each number in an equal pill and lines the titles up in one column.
- placement: at('container', 'top-left') }; // plus its padding
+ placement: { ...at('container', 'top-left'), size: { width: mm(12.7) } } };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 →
Sandbox check · headingHierarchy
Heading hierarchy jump
Why. A heading skips a level, such as an H1 followed directly by an H3.
Fix. Use the next level down, or restyle the level you meant instead of skipping one. Docs →
- The seventh level is a level-6 heading with the style
level7, so no head in the sample drops more than one level below the head before it: The trench, Tools for the trench, STEEL BARS and Rock bar run 4, 5, 6, 6. The Sandbox warning “Heading hierarchy jump” reports exactly such a skip, so it never appears on this chapter.
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Fonts
- IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


