Configuration: callout boxes

#Callout styles

The calloutStyles property declares the named box styles a document applies with a :::callout{type="…"} container — notes, tips, warnings, learning objectives, any content set apart from the running text in a tinted or bordered box. One neutral style, note, ships by default (light grey background, no border, no stripe, no icon, no title), so :::callout works without any configuration; declaring calloutStyles replaces that default list.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#The :::callout container

A :::callout{type="<id>"} line opens the box and a bare ::: line closes it. The fence accepts five attributes — type (the style id), title (overrides the style's title), span, placement and columns (override the style's values) — and the content in between is laid out inside the box: an optional title, then the paragraphs, lists, blockquotes, formulas or resource embeds, each typeset with the style's body / lists typography (headings keep their usual styles). Margins between children collapse as in the running text; the interior leaves the baseline grid, and the flow snaps back onto it after the box with at least marginBottom below (the grid wins; the margin is a minimum — the same convention resources follow). A style with snapToGrid: false keeps the exact marginBottom instead, and the text after the box stays off the grid until the next heading or list end. A heading immediately before a callout keeps with it.

Limits in this version:

• A callout is kept whole unless its style sets keepTogether: false. When it does not fit the remaining column space it moves whole to the next column or page — also out of an empty column that float bands or a band cap have cut short, as long as a full column would hold it. A box taller than a full column splits instead, like a splittable one; only one that no cut can split (a figure or table taller than the column, or a splitMinLines no cut satisfies) is placed anyway and overflows; the layout then records a calloutOverflow warning (VDTDocument.warnings), which the sandbox lists. A :::columns group is cut like the box around it, between its sub-columns (since postext 1.25); it stays whole, and can overflow the same way, only with layout.flowColumns: false or inside a nested box. A splittable box leaves the part that fits behind — whole children, or the lines of a paragraph down to splitMinLines on each side (a figure, table or display formula alone is enough for a side) — and continues in a box without icon on the next column or page, without the title unless the style repeats it, and optionally with a marker under the part it leaves (see Marks on a split box).
• Floats yield to an unbreakable box. When the block right after a figure's reference is a keepTogether callout, a slot that would leave the box no column of the current band to land in (the referencing column or an empty one after it, which held it before the float) is not taken: the figure moves on to its next slot, usually the next page, and the box stays in flow — as a compositor would set it, rather than pushing the box off the page and leaving the column with the figure alone.
• span: 'page' in a multi-column layout makes the box a span block: it is laid out at the full content width and splits the page into column bands — the text columns above it are closed at the cut line, the box takes its own full-width column, and a fresh band of text columns opens below it, so the flow continues under the box in every column. Where the columns are level — at the top of a page, right below a span: 'page' opener heading, right below another span block, or right below a top float band — the box simply cuts there. Arriving mid-page, with the columns uneven, it is set the way a compositor would: the text above it is cut level across all columns (the engine re-runs placement with the band's columns shortened to the same number of grid lines, so the text overflows from column to column naturally and every orphan, widow and keep-with-next rule still applies), the box spans the page, and the columns resume below it. The cut takes a couple of extra placement passes; when the cut line would leave no room for the box plus the widow minimum of body lines below it, or no arrangement fits after a few attempts, the box moves to the top of the next page. The text above keeps to the cut: a paragraph that cannot start in the few lines a column under a figure keeps above it goes on to the next column (the figure then stands alone in its column), and when a block would still run past the cut, the cut is taken a line lower rather than where that block ends. A split box that opens the band is cut there too, so its rest never runs past the cut. With headings.balancing.beforeSpan (the default) the band it leaves is cut level behind it — like a chapter's closing band — and, when the style allows splitting (keepTogether: false), the part of the box that fits under the levelled columns closes the page and the rest opens the next one; with beforeSpan: false the page it leaves is simply balanced as usual, without forcing a page break. A heading right before a span block does not travel with it. In single-column layouts span: 'page' is simply inline.
• placement: 'fixed' takes the box out of the flow: it is laid out (width: 'auto' shrink-wraps the title; 'fill' takes the width of the text column under the anchor point) and pinned to the page where it occurs in the flow at the position fixed.anchor / fixed.offset describe — the bottom-left corner of the content area by default. The text columns it covers give up that zone (cut from the bottom, or from the top when the column is still empty), exactly like a float band; when the zone already holds text, a float or a span block, the box moves to the next page. A fixed box that closes the chapter (the next block is a chapter opener, a :::part, a float-barrier box or the end of the document) first levels the columns above it (headings.balancing.trailing), so a short closing page ends level with the badge beneath. Frame and children live in page.floats and render outside the column clip in every backend.
• placement: 'top' | 'bottom' floats the box like a resource: it leaves the flow where it occurs and takes the first free band after that point — the foot of the current page ('bottom'), or the head / foot of the next page the flow opens — at the column width (span: 'column') or the full content width (span: 'page'); the text after it fills the page it left. Its frame and children go to page.floats, as a fixed box does. A floated box heading a fresh page is set before the figures waiting for that page, and a figure cited on an earlier page that then fits under it takes the rest of that page even when fewer than three text lines would remain (a gallery page: box plus figure, no text between them). A span: 'side' box never floats: it stacks beside the text whatever its placement. With columns above 1 (in the style or as the fence's attribute, since postext 1.18) a span: 'column' box takes that many adjacent columns: the head of a run of empty columns that start level, or the foot of the current column and of the empty ones after it, as in :::callout{placement="top" columns="2"}.
• width: 'auto' shrink-wraps the title only; children are ignored.
• A :::callout nested inside another callout is a box of its own: it is laid out with its own style (background, border, radius, padding, stripe, title, icon, marker, label, typography) at the full inner width of its parent and stacks as one child of it, its marginTop / marginBottom collapsing with its neighbours. Its span and placement (fence or style) are ignored — a nested box always flows inside its parent — and so are floatBarrier and snapToGrid. Boxes nest to any depth and may sit inside a :::columns group (each one whole, in one column). When the parent splits, the cut falls before or after a nested box, or inside it when the nested style allows splitting; every fragment redraws the frames it cuts through, and a nested box continued from the previous fragment drops its title and icon, like a top-level continuation.
• A :::columns{count=N} … ::: group among the children lays those children out in N columns of equal width, columnGap apart, inside the box: the run is cut at the block or line boundaries that level the columns best (a paragraph or list item cut mid-way continues at the head of the next column without its bullet), every column starts at the group's top and the group is as tall as its tallest column; the children after it return to the full width. A box that splits (keepTogether: false, or taller than a column) cuts inside a group too, between its columns: a snake group fills its columns in turn and goes on in the next fragment, a parallel one (breaks) goes on stream by stream (since postext 1.25; see Document format › :::columns). A gap on the fence replaces columnGap for that group, and rule draws a rule down each gutter. Use it for a two-column summary of key points, or the tables of a wide box set side by side.
• The fence's sixth attribute, label, prints on the style's label tab (see label above) — :::callout{type="box" label="BOX 1-1" title="The octet rule"}; without a label style the attribute is ignored.

In the VDT the box is a type: 'callout' frame block whose decoration (background, stripe, icon, title) lives on designOverlay, followed by its child blocks in the same column; the frame and every child carry the fence's containerId. A nested box is a type: 'callout' frame of its own among the children, followed by its blocks; they keep the top-level fence's containerId (placement and balancing still see one unit) and add calloutPath, the container ids of the nested fences around them, outermost first (a nested frame's own id is the last entry). The tagged PDF gives each nested box a Div inside its parent's. Icon images resolve like resource images: the canvas image registry, the HTML resourceImageUrl option and the PDF resourceBytes provider.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Numbered statements and proofs

A style with numbering counts its boxes, as LaTeX's amsthm counts theorem environments (since postext 1.19). Each box prints its label and number — "Theorem 2." opening its first paragraph — and the fence's title follows the number in parentheses: :::callout{type="theorem" title="Bradley–Terry"} opens with "Theorem 2 (Bradley–Terry).". A box opened with an identifier ({#thm:main}) is a target of cross-references, which print "Theorem 2" (:ref{id="thm:main"}), and \ref{thm:main} or style=number prints 2.

A proof is a style with an unnumbered label and an end mark:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

In a book laid out chapter by chapter the counters go on from the previous chapter (LayoutContinuation.statementCounters, which continuationAfter fills), and the book outline gives each numbered box's anchor its label (OutlineEntry.numberLabel), so a reference from another chapter prints it.

#Typography inside a box

A box sets its content with its own body and lists typography; everything else keeps the document's styles:

• Paragraphs take the box's body: face, size, leading, colour, emphasis colours, weights, italic, smallCaps, alignment, hyphenation, indent and paragraph spacing. A field left unset inherits bodyText. An inherited emphasis colour keeps its palette link, so bold, italics and :ref labels in a box change with colorPalette as they do outside it. (Up to postext 1.4 bold in a box stayed #295AA3 whatever the Main Color was.)
• Bullet lists take the box's lists (bullet character, colour, glyph size and weight, indent, gap, item spacing) over unorderedLists, and their text is the box's body text. A lists.bulletChar or lists.color that differs from the document's (unorderedLists) replaces the bullet or colour of every level; one that repeats it, or is left unset, leaves each level its own (unorderedLists.levels), so nested dashes survive in the box.
• Ordered lists take lists.indent, gap and itemSpacing, and lists.color whenever the style sets it — also when it is the document's bullet colour; a style that leaves it unset keeps the numbers in orderedLists.color. (Up to postext 1.4 the colour reached the numbers only when it differed from unorderedLists.color, so setting it to that very colour did nothing.) The number itself — its face, size and separator — comes from the global orderedLists, since lists has bullet fields only: style a box's numbers there.
• :::paragraphs inside a box use their paragraph style, in nested boxes too. The fields the style leaves unset inherit the document's bodyText, not the box's body (nor its italics or small capitals).
• :::columns groups have no style of their own: every column shares the box's body and list typography, and columnGap sets the gap between them.
• Blockquotes take the box's body face, size and weights (italic and grey, as in the running text), and its small capitals. Headings keep the heading styles; display formulas the math settings.
• Figures and tables keep the document's caption and table styles, at the box's inner width; their regular and bold weights follow the box's body weights.
• Chips keep their chip style; an em size is read against the box's body size.
• :::space is measured in the box's body lines (see :::space for where it is dropped).
• A nested box takes its own style in full; its span, placement, floatBarrier and snapToGrid are ignored.

#Marks on a split box

When a box splits across columns or pages (keepTogether: false, or a box taller than a column), each part after the first opens without the title and the icon, and by default nothing tells the reader that the box goes on. Two options add the marks a book or a script uses:

• repeatTitle: true repeats the title at the head of every continuation, followed by continuedSuffix — "Key points (cont.)" by default. The repeat takes the title style, so with textTransform: 'uppercase' it gives a screenplay's "HAMLET (CONT'D)". The icon and the label tab stay on the first part.
• continuesMarkerEnabled: true sets continuesMarker — "Continued", or "Continúa" in a Spanish document — under the last line of every part that goes on, inside the box, in the box's body face and size: italic unless continuesMarkerItalic is false, flush right unless continuesMarkerAlign says 'left' or 'center'. The marker takes room in the part it closes, and the cut is chosen so that it fits.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

The part that closes the page ends with "(MORE)", and the next page opens with "HAMLET (CONT'D)". Both are pagination furniture: in an accessible PDF they are artifacts and in the HTML they are hidden from assistive technology, so the title is read once. In the VDT they are designOverlay text blocks flagged artifact: true.