Skip to main content
Recipe number 45

Cookbook · Chapter 3 · Headings & openers

Side heads, hanging numbers and run-in heads

A competition brief whose section titles stand in a margin channel on the text's baselines, with subsection numbers hung in the gutter and run-in heads in red.

  • Trim 210 × 297 mm
  • Column and a half, 7 mm gutter
  • Mona Sans 10/14
  • DM Mono
  • Mona Sans@tnum
  • Noto Serif Display
  • 5 pages
  • Level
  • Postext 1.65.0
  • Laid out in 86 ms
  • 263 lines of code

In short

A town council's call for designs to turn an old fish market into a library. Section titles sit in a wide left margin, level with the first line of the text beside them.

What you'll build

Five A4 pages of an architectural competition brief, in which the council of Puerto Lince, a fictional Spanish port, calls for designs to turn its 1931 fish market into the town library. The layout follows Swiss municipal reports. A 50 mm channel runs down the left of every page, and each section opens on a red number and a black rule across the whole text block. The section's title stands in the channel in Noto Serif Display, level with the first line of the text. Subsection numbers hang in the gutter in red DM Mono, so every subsection title keeps the text's left edge. The judging criteria in section 4 open on bold terms in red. Page 1 sets a 58 pt title over a site plan, a plan of the plot stands in the channel on page 2, and an elevation of the quay front opens page 3.

This recipe answers

  • How do I number headings (1, 1.1, 1.1.1) and style each level differently?
  • How do I make a column-and-a-half layout, with a wide text column and a narrow side column?
  • How do I control where a figure goes: top of page, across both columns, exactly here, or in the margin?
  • How do I colour key terms (bold or italic) in the body or inside boxes?

The short answer

script.js · lines 56–81in full code
// The heading stays in the flow and keeps its number, but its design has no {titleText}:
// it prints the number in the channel and a rule from there to the column's right edge,
// both reserve: false, or the box below would keep a float gap under them (a line lower).
const [NUMBER, RULE] = [8.5, 0.75]; // pt: the DM Mono number, whose figures are 0.7 em tall
// Centre the rule on the figures: their baseline is 0.8 of the line down, less 0.35 em.
const RULE_Y = pt(NUMBER * (0.8 - 0.7 / 2) - RULE / 2);
const h2 = { level: 2, numberingTemplate: '{2}', lineHeight: pt(LEAD), // one grid line
  marginTop: pt(2 * LEAD), marginBottom: pt(0), advancedDesign: { enabled: true, slot: {
    elements: [
      { kind: 'text', id: 'number', content: '{number}', fontFamily: LABEL, fontWeight: 500,
        fontSize: pt(NUMBER), lineHeight: 1, color: col('signal'), reserve: false,
        placement: at('container', 'top-left', mm(-HANG)) },
      { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(RULE), reserve: false,
        color: col('ink'), placement: { ...at('#number', 'right-of', mm(2), RULE_Y),
          size: { width: 'fill' } } },
    ] } } };
// The title goes in a box fenced right after the heading: span="side" stands it in the
// channel on the grid line where the text resumes (gotcha: side-box-starts-at-fence).
// Attributes at the end of the line stay with the heading.
const sideHeads = (md) => md.replace(/^## (.+?)(\s*\{[^}]*\})?$/gm,
  (line, title) => `${line}\n\n:::callout{type="sidehead" span="side"}\n${title}\n:::`);
// The box has no background and no padding, and it takes the text's leading, so each
// line of the title sits on a baseline of the text beside it.
const sidehead = { id: 'sidehead', backgroundEnabled: false,
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  body: { fontFamily: DISPLAY, fontSize: pt(13.5), lineHeight: pt(LEAD) } };

Side heads: the heading draws a number and a rule, a box prints the title

Ingredients

Type
Mona Sans, Noto Serif Display, DM Mono (SIL OFL 1.1)
Assets
None: every picture is drawn in code

Method

#1 · Print the section title from a box in the channel

The code is the short answer above. A heading reserves room down to the lowest element of its design, so a title drawn in the channel level with the section's first line would push the text down a line, and two for a two-line title. The heading's design draws only the number and the rule instead, and sideHeads() copies the text of each ## Title into a :::callout fenced right after the heading. With span="side" that box leaves the flow and stands in the channel on the grid line where the text resumes (callout styles). The number and the rule set reserve: false: otherwise a box in the channel keeps a float gap, one line, under the heading elements standing there, and the title would drop to the text's second line. Boxes and body text both set a line's baseline 0.8 of the line height down, so a box on the text's 14 pt leading puts each line of a two-line title on a baseline of the paragraph beside it. The Markdown stays a plain ## Schedule of accommodation. Since the heading's design prints no {titleText}, the Sandbox lists the warning Heading title not referenced, although the box prints the title.

Page 2: the number and the rule come from the heading, the title from the box in the channel, level with the first line of the text. The plot plan stacks under it.

#2 · Keep the channel for heads and figures

script.js · lines 46–52in full code
const layout = {
  layoutType: 'oneAndHalf',
  sideColumnPercent: (SIDE / CONTENT) * 100, // 50 of the 178 mm between the margins
  sideColumnSide: 'left', // on every page: the brief is printed on one side of the sheet
  sideColumnRole: 'floats', // no text in the channel: what span: 'side' sends, side captions
  gutterWidth: mm(GUTTER),
};

sideColumnRole: 'floats' keeps the text out of the channel (layout types). After the opener, the channel holds only the six section titles and the plot plan, both sent there with span: 'side', and the captions of tables 1 and 2. The side column defaults to 'right', and a brief printed on one side of the sheet keeps it on the same side of every page. sideColumnSide: 'left' puts it on the left, where each section title is read before its text.

#3 · Hang the numbers and run the smallest heads in

script.js · lines 85–102in full code
// The title keeps the text's left edge; the number, right-aligned in a 12 mm box, ends
// 2 mm short of it. The box needs that fixed width: an 'auto' width is clamped to the
// column and would shrink to nothing out here.
const H3 = { size: 10.5, number: 9 }; // pt; two boxes one grid line tall share a baseline
const h3 = { level: 3, numberingTemplate: '{2}.{3}', fontSize: pt(H3.size),
  lineHeight: pt(LEAD), marginTop: pt(LEAD), marginBottom: pt(0),
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: TEXT, fontWeight: 600,
      fontSize: pt(H3.size), lineHeight: LEAD / H3.size, color: col('ink'), align: 'left',
      overflow: 'wrap', placement: { ...at('container', 'top-left'), size: { width: 'fill' } } },
    { kind: 'text', id: 'number', content: '{number}', fontFamily: LABEL, fontWeight: 500,
      fontSize: pt(H3.number), lineHeight: LEAD / H3.number, color: col('signal'),
      align: 'right', placement: { ...at('#title', 'left-of', mm(-2)),
        size: { width: mm(12) } } },
  ] } } };
// Level 4 is not a heading: '**Accessibility.** A wheelchair user…' opens its paragraph.
// No other paragraph has bold; table cells keep tableStyle's ink, so Total stays black.
const runIn = { boldColor: col('signal') }; // spread into bodyText

The subsection title starts on the column's left edge. Its number is anchored 'left-of' the title, right-aligned in a 12 mm box that ends 2 mm short of the text, so numbers such as 2.1 and 3.3 hang in the gutter and every title lines up with the text under it (element placement). The box needs a fixed width. An 'auto' width is clamped to the column. Out in the gutter that leaves no width at all, and the number is not drawn. Level 2 prints '{2}' and level 3 '{2}.{3}', because with {1} every number would start with the 1 of the brief's one H1. The criteria in section 4 are a fourth level set without a heading. Each paragraph opens on a bold term, and bodyText.boldColor prints it in red (body text). No other paragraph has bold, and table cells take their colour from tableStyle, so the bold Total row of table 1 stays black.

#4 · Give each figure and table its own placement

script.js · lines 335–369in full code
// The plot plan stands in the channel; the elevation crosses channel and column at the
// head of the next page; the table of areas floats to the head of the text column, with
// its caption beside it in the channel; the timetable sits where ::resource puts it, and
// its caption takes the channel too (captionSide serves an inline embed from 1.28).
const PLAN_W = 44; // mm: the plot plan, 88 m wide at 1:2000
const resource = (id, typeId, rest) => ({ id, typeId, createdAt: 0, updatedAt: 0, ...rest });
const drawing = (id, width, height, rest) => resource(id, 'figure', { kind: 'svg',
  svg: { fileId: `${id}.svg`, width, height }, ...rest });
const resources = [
  drawing('parcela', PLAN_W * 10, 400, {
    placement: { span: 'side', width: PLAN_W / SIDE }, // 44 mm of the channel's 50
    caption: t({ en: 'The plot, 1:2000. Market hall and weighbridge hut in grey; six tamarisks '
      + 'along the north edge. Red arrows: possible entrances; grey arrow: service.',
    es: 'La parcela, 1:2000. Lonja y caseta de básculas, en gris; seis tamarindos en el '
      + 'borde norte. Flechas rojas: accesos posibles; flecha gris: servicio.' }),
    altText: t({ en: 'Plan of the plot with the hall, the hut, six trees and three entrances.',
      es: 'Planta de la parcela con la lonja, la caseta, seis árboles y tres accesos.' }) }),
  drawing('fachada', 1780, 300, { placement: { position: 'top', span: 'page' },
    caption: t({ en: 'Quay front, 1:300. In red, the four frames at the east end, where the '
      + 'reinforcement has corroded.',
    es: 'Fachada al muelle, 1:300. En rojo, los cuatro pórticos del extremo este, con '
      + 'las armaduras corroídas.' }),
    altText: t({ en: 'Elevation of the hall: thirteen vaults, eleven arches, four frames in red.',
      es: 'Alzado de la lonja: trece bóvedas, once arcos y cuatro pórticos en rojo.' }) }),
  resource('programa', 'table', { kind: 'table', table: { ...programme, styleId: 'figures' },
    placement: { position: 'top', captionSide: true }, caption: t({
      en: 'Schedule of net floor areas.', es: 'Programa de superficies útiles por zonas.' }) }),
  resource('calendario', 'table', { kind: 'table', table: calendar,
    placement: { position: 'here', captionSide: true },
    caption: t({ en: 'Competition timetable.', es: 'Calendario del concurso.' }) }),
  // No :ref cites the site plan: only the opener's image element draws it.
  drawing('situacion', MAP.w * 10, MAP.h * 10, { altText: t({
    en: 'Site plan of the Poniente quay with the market hall’s plot in red.',
    es: 'Plano de situación del muelle de Poniente con la parcela de la lonja en rojo.' }) }),
];

The plot plan goes into the channel with span: 'side' and stacks under the side head of section 2 (placement). width: PLAN_W / SIDE makes it 44 mm wide, which puts its 88 metres at exactly 1:2000. The facade elevation is a 'top' float across the page. It is cited on page 2 and opens page 3, since a float is never placed above its reference. The table of areas, also cited on page 2, floats to the head of the text column on page 3, under the elevation. captionSide: true stands its caption in the channel, level with the table's top. The timetable sits where ::resource puts it, at the end of the brief, and captionSide: true stands its caption in the channel too, beside section 6.3. Mona Sans sets proportional figures by default, so in a right-aligned column 120 and 560 do not line up digit under digit. A named table style, tableStyles: [{ id: 'figures', figureStyle: 'tabular' }], picked by table 1 with styleId: 'figures', turns on the font's tnum: its tabular set has a slashed zero, close to the DM Mono numbers. The timetable's dates keep the font's own figures (figure styles).

#5 · Open the brief on the site plan

script.js · lines 106–131in full code
const MAP = { y: 68.5, w: CONTENT, h: 52 }; // mm: from the top of the text block
const display = { fontFamily: DISPLAY, fontWeight: 300, color: col('ink'), align: 'left',
  overflow: 'wrap' };
const opener = { enabled: true,
  // The plan's foot falls between two grid lines. A floor on the next one leaves the rule
  // of section 1 as far from its text as the rule of every later section.
  minHeight: mm(GRID * Math.ceil((MAP.y + MAP.h) / GRID)),
  slot: { elements: [
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...label, color: col('signal'),
      placement: at('container', 'top-left', mm(HANG)) },
    { kind: 'text', id: 'series', content: '{subtitle}', ...label,
      placement: { ...at('container', 'top-left'), size: { width: mm(SIDE) } } },
    { kind: 'text', id: 'title', content: '{titleText}', ...display, fontSize: pt(58),
      lineHeight: 0.96, placement: { ...at('#kicker', 'below', mm(0), mm(4.5)),
        size: { width: mm(MAIN) } } },
    { kind: 'text', id: 'lead', content: '{attr.lead}', ...display, italic: true,
      fontSize: pt(14), lineHeight: 1.3, placement: { ...at('#title', 'below', mm(0), mm(5)),
        size: { width: mm(MAIN) } } },
    { kind: 'text', id: 'legend', content: '{attr.map}', fontFamily: TEXT, fontSize: pt(7.5),
      lineHeight: 1.4, color: col('muted'), align: 'left', overflow: 'wrap',
      placement: { ...at('#lead', 'align-top', mm(-HANG), pt(2)),
        size: { width: mm(SIDE - 6) } } },
    { kind: 'image', id: 'map', resourceId: 'situacion', // across the channel and the column
      placement: { ...at('container', 'top-left', mm(0), mm(MAP.y)),
        size: { width: mm(MAP.w) } } },
  ] } };

With span: 'page' the opener's container is the whole text block, channel included (span and advanced design). The kicker and the title are placed 57 mm in, on the text column's left edge, and the plan runs across channel and column. Without it the container is the text column, every element moves 57 mm to the right, and the title, the lead and the plan run past the right edge of the page. The design reserves room down to the plan's foot, which falls between two grid lines. A minHeight rounded up to the next grid line leaves the rule of section 1 as far from its text as the rule of every later section. The kicker, the lead and the map legend are attributes of the # Competition brief line.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 045 · Side heads, hanging numbers and run-in heads ═══════
// https://postext.dev/en/cookbook/side-heads-hanging-numbers
// Code: MIT · Text: original (CC BY 4.0) · Drawings: made in code (MIT)
// Fonts: Mona Sans, Noto Serif Display, DM Mono (SIL OFL 1.1) · Needs postext ≥ 1.65.0
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, defaultResourceTypes,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'side-heads-hanging-numbers';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // a Swiss municipal report: black, white and one signal red
  ink: '#17171a', // text and rules
  signal: '#d42a1f', // section numbers, run-in heads, the plot on the plans (5.1:1)
  tint: '#f9dcd7', // the plot's ground on the plans
  sea: '#d8e2e8', // water on the plans
  stone: '#cacad0', // built ground on the plans
  rule: '#c3c3ca', // hairlines under the running head and in tables
  muted: '#5e5e67', // running heads, legends, the colophon (6.4:1)
  paper: '#ffffff',
};
// Every colour is linked to its palette entry by id.
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.signal })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, LABEL] = ['Mona Sans', 'Noto Serif Display', 'DM Mono'];
const TRIM = { width: 210, height: 297 }; // mm: A4, like every document of the competition
const [TOP, LEFT, RIGHT] = [26, 16, 16]; // mm; not mirrored: the brief prints one-sided
const LEAD = 14; // pt: the body leading, the pitch of the baseline grid
const LINES = 50; // grid lines in the text block
const PT = 25.4 / 72; // mm in a point
const GRID = LEAD * PT; // mm: one line of the grid
const CONTENT = TRIM.width - LEFT - RIGHT; // 178 mm
const [SIDE, GUTTER] = [50, 7]; // mm: the margin channel on the left, and the gap after it
const MAIN = CONTENT - SIDE - GUTTER; // 121 mm: the text column
const HANG = SIDE + GUTTER; // mm from the channel's left edge to the text's left edge
const at = (to, edge, x = mm(0), y = mm(0)) => ({ anchor: { to, edge }, offset: { x, y } });
// Kickers, running heads and folios: tracked capitals in the mono.
const LABEL_PT = 7.5;
const label = { fontFamily: LABEL, fontWeight: 500, fontSize: pt(LABEL_PT), lineHeight: 1.35,
  letterSpacing: pt(1.2), textTransform: 'uppercase', color: col('muted'), align: 'left' };

// #region channel: one text column, and on its left a channel for boxes and figures only
const layout = {
  layoutType: 'oneAndHalf',
  sideColumnPercent: (SIDE / CONTENT) * 100, // 50 of the 178 mm between the margins

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

#Rule the text column only

Anchor the rule to the heading's own box instead of the number, and it runs from the text's left edge to the column's right edge, with only the number and the title in the channel.

-        color: col('ink'), placement: { ...at('#number', 'right-of', mm(2), RULE_Y),
+        color: col('ink'), placement: { ...at('container', 'top-left', mm(0), RULE_Y),

Pitfalls

Pitfall

A side box starts level with the block after its fence

In postext 1.4.1 a span: 'side' box stands in the side column at the height the text has reached at its fence, on the next grid line, and under any box already there. Fence a gloss just before the paragraph it explains: fenced after it, the gloss starts beside the next paragraph. A box that would run past the column's foot slides up until its foot sits on the column's foot, as far as the box above it allows; one that still does not fit waits for the side column of the next page. Margin notes →

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 · headingAdvancedWithoutTitleText

Heading title not printed

Why. An advanced design has no element that prints {titleText}, so the heading's own words never appear.

Fix. Add a text element with {titleText}, unless the heading is meant to be invisible. Docs →

  • A side figure takes the head of the channel on the page that cites it, and a side head fenced after it stacks under the figure, below the start of its own section. Cite side figures after the section head of their page, as section 2 cites the plot plan.
  • An inline embed (position: 'here') takes captionSide from postext 1.28: the timetable's caption stands in the channel on page 5, as the caption of the table of areas does on page 3. The caption needs the channel free beside the table. Where a side head or a side figure already stands there, it stays under the table.

Credits

Text
Original prose, CC BY 4.0
Fonts
Mona Sans (SIL OFL 1.1) · Noto Serif Display (SIL OFL 1.1) · DM Mono (SIL OFL 1.1)
Sandbox