Skip to main content
Recipe number 32

Cookbook · Chapter 6 · Boxes & notes

Annotated classic with margin glosses

Alice’s mad tea-party as an annotated edition: green and red glosses in the outer margin, beside the lines they explain, each called by a letter in its colour.

On this page

pp. 82–83 · 2–3 of 3

  • Trim 156 × 234 mm
  • Column and a half, 4.5 mm gutter
  • Unna 9.5/14
  • Cormorant SC
  • Rozha One
  • 3 pages
  • Level
  • Postext 1.57.1
  • Laid out in 68 ms
  • 207 lines of code

In short

A few pages of Alice in Wonderland with an editor's notes in the side margin. Each note sits next to the lines it explains, marked by a coloured letter.

What you'll build

The opening of chapter VII of Alice’s Adventures in Wonderland, the mad tea-party, set as three pages of an annotated edition on a 156 × 234 mm trade page. Carroll’s text runs in one justified column of Unna, some 66 characters to the line. A 33 mm channel at the fore-edge holds the editor’s eight glosses, each beside the paragraph that carries its letter, so they run down the right of a recto and the left of a verso. Glosses on words and jokes are green, those on history red, and each letter in the text takes the colour of its gloss. The chapter opens under a watercolour of the tea-table seen from above, followed by the numeral, the title in Rozha One and an italic headnote with a green drop cap; the note on this edition sits in the margin beside the headnote.

This recipe answers

  • How do I set margin notes or glosses beside the paragraph they explain?
  • How do I do footnotes?
  • How do I make a column-and-a-half layout, with a wide text column and a narrow side column?
  • How do I add an author line, a standfirst or a lead with a drop cap to an opener?

The short answer

script.js · lines 36–61in full code
const layout = {
  layoutType: 'oneAndHalf', // one text column and a narrower side column
  sideColumnPercent: 26, // of the 127 mm between the margins: a 33 mm channel
  sideColumnRole: 'floats', // no text runs in it: it holds side boxes and figures
  sideColumnSide: 'outer', // at the fore-edge, which mirrored margins move page by page
  gutterWidth: mm(4.5), // the text column keeps 127 − 33 − 4.5 = 89.5 mm
};
// A gloss is :::callout{type="note" span="side" title="a · …"} in the Markdown.
// span="side" moves it out of the flow into the channel, level with the block after
// the fence, so the fence goes just before the paragraph that carries its letter.
// Glosses never float. One that meets the gloss above stacks under it. One that would
// run past the column's foot slides up, as far as the gloss above allows, until its
// foot sits on the foot; if it still does not fit, it waits for the next page
// (gotcha: side-box-starts-at-fence).
const gloss = (id, hue) => ({ id,
  backgroundEnabled: false, // one device: a hairline over the gloss, in its colour
  stripe: { enabled: true, side: 'top', width: pt(0.5), color: col(hue) },
  padding: { top: mm(1.5), right: pt(0), bottom: pt(0), left: pt(0) },
  // Cormorant SC draws lower case as small capitals: the title needs no textTransform.
  titleStyle: { fontFamily: LABEL, fontWeight: 600, fontSize: pt(8.5),
    letterSpacing: pt(0.3), color: col(hue), gap: mm(0.8) },
  // Face and colours come from bodyText. A box body also inherits its 4 mm first-line
  // indent, which a gloss sets back to 0.
  body: { fontSize: pt(7.8), lineHeight: pt(10), textAlign: 'left',
    firstLineIndent: pt(0) } });
const calloutStyles = [gloss('note', 'lawn'), gloss('context', 'jam')]; // words, history

A float-only channel at the fore-edge, and two gloss styles for it

Ingredients

Type
Unna, Rozha One, Cormorant SC (SIL OFL 1.1)
Assets
  • tea-table-1560.jpg
  • The tea-table seen from above, a watercolour (Generated With Diffusion Models, original)

Method

#1 · Give the fore-edge to the glosses

The code is the short answer above. In a column-and-a-half layout, sideColumnPercent: 26 gives the side column 33 mm of the 127 mm between the margins, and the text keeps 89.5 mm after the 4.5 mm gutter. sideColumnRole: 'floats' keeps Carroll out of the side column, which holds only what is placed there with span: 'side'. A footnote waits at the foot of the column, under a rule; in the margin each gloss stands level with the line it explains, and the glosses take no lines from the text column. The two gloss styles differ only in the colour of the hairline and the title, so the reader can tell a gloss on a word from a gloss on history before reading it.

#2 · Mirror the page so the channel follows the fore-edge

script.js · lines 75–86in full code
const PT = 25.4 / 72; // mm in a point
const [TRIM_W, TRIM_H] = [156, 234]; // mm
const [TOP, BOTTOM, INNER, OUTER] = [22, 22, 15, 14]; // mm: 38 lines of text
const page = { width: mm(TRIM_W), height: mm(TRIM_H), dpi: 150,
  backgroundColor: col('paper'),
  // left is a recto's inner margin; mirror swaps the sides on a verso, and 'outer' moves
  // the channel with them: right on a recto, left on a verso.
  margins: { top: mm(TOP), bottom: mm(BOTTOM), left: mm(INNER), right: mm(OUTER),
    mirror: true } };
const CONTENT_W = TRIM_W - INNER - OUTER; // 127 mm
const SIDE_W = CONTENT_W * layout.sideColumnPercent / 100; // 33 mm: the glosses' measure
const TEXT_W = CONTENT_W - SIDE_W - layout.gutterWidth.value;

With mirror: true the margins swap on every verso, and sideColumnSide: 'outer' moves the channel with them, so the glosses run down the right of page 81 and page 83 and down the left of page 82. Top and bottom margins of 22 mm leave 190 mm, room for 38 lines of 14 pt, and each gloss starts on a line of the same grid.

#3 · Fence each gloss before the paragraph it explains

script.js · lines 90–104in full code
const bodyText = { // justified and hyphenated (en-us) by default
  // Copy-fitted to the 89.5 mm column: at 9.5 pt '“Have some wine,” the March Hare said in
  // an encouraging tone.' fits one line. At 10.4 pt every measure from 77 to 93 mm left
  // it a short last line: 'couraging tone.', 'aging tone.', 'ing tone.' or 'tone.'.
  fontFamily: TEXT, fontSize: pt(9.5), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), firstLineIndent: mm(4),
  // The chapter's first paragraph is set flush, though the fences of glosses a and b stand
  // between the heading and it: a box that leaves the flow is not the block after a heading.
  indentAfterHeading: false,
  // Unna's space is narrow, 0.22 em. At the default 0.6 the line breaker set 'Alice felt
  // dreadfully puzzled. The Hatter’s remark seemed to have' with its spaces at 0.69.
  minWordSpacing: 0.75,
  // The dictionary divides the heroine's name, 'said Al-' | 'ice indignantly' on page 81.
  // The list keeps it whole wherever it stands; every other word is divided as before.
  hyphenation: { exceptions: ['Alice'] } };

A box with span="side" on its :::callout fence leaves the flow and stands in the channel level with the block after the fence, so each gloss is fenced just before the paragraph that carries its letter, as below. Glosses a and b belong beside the first paragraph, which puts their fences between the heading and that paragraph. A box that leaves the flow does not count as the block after the heading, so indentAfterHeading: false still sets that paragraph flush. The body is copy-fitted to the column: at 9.5 pt the paragraph that opens “Have some wine,” fits on one 89.5 mm line, while at 10.4 pt every measure from 77 to 93 mm left it a short last line such as “ing tone.” or “tone.”. Unna’s word space is narrow, 0.22 em, and at the default minWordSpacing of 0.6 one line on page 83 had its spaces squeezed to 0.69 of that width; minWordSpacing: 0.75 rules that line out. On page 81 the dictionary divided the heroine’s name, “Al-” and “ice”, so that paragraph is fenced in :::paragraphs{style="whole"}, a style with hyphenation: false; its one break is a soft hyphen (U+00AD) typed in “together”.

:::callout{type="context" span="side" title="c · Hair"}
Tenniel drew Alice with long, loose hair. …
:::
 
“Your hair wants cutting,”:chip[^c^]{style="context"} said the Hatter. …

#4 · Print each letter in the colour of its gloss

script.js · lines 65–71in full code
// A letter in the text is a chip named after its gloss's type, :chip[^a^]{style="note"}:
// the Markdown has no mark for coloured text, and a chip style sets a colour. With no
// fill, outline, padding or gap the chip adds no width, so the lines break as they would
// with a plain ^a^.
const letter = (id, hue) => ({ id, backgroundEnabled: false, borderWidth: pt(0),
  paddingX: pt(0), gap: pt(0), color: col(hue), bold: true });
const chipStyles = [letter('note', 'lawn'), letter('context', 'jam')];

Markdown has no mark for coloured text, but a chip style sets a text colour, so each letter is a chip whose style has the same name as the type of its gloss. :chip[^c^]{style="context"} prints a red c, the red of gloss c’s hairline and title. With no fill, outline, padding or gap the chip adds no width, and every line breaks where it did with a plain ^c^.

#5 · Open the chapter under the tea-table

script.js · lines 108–155in full code
const HEADPIECE = 72; // mm: the depth of the painting at the head of the page
const HEADNOTE = { size: 9.8, lead: LEAD }; // pt: the headnote keeps the body's leading
const CAPS = { text: 0.597, initial: 0.56 }; // cap heights, em: Unna and Rozha One
// The initial's size: its capital runs from the first line's cap height down to the
// last baseline it spans. At the default size it stops short of the first line's capitals.
const dropSize = (lines) => pt(((lines - 1) * HEADNOTE.lead + CAPS.text * HEADNOTE.size)
  / CAPS.initial);
const below = (id, y, width) => ({ anchor: { to: `#${id}`, edge: 'below' },
  offset: { y: mm(y) }, size: { width } });
// The opener reserves the height of its lowest element, rounded up to the grid, and the
// heading's default bottom margin adds one blank line: with a four-line headnote the
// text starts on line 23. The kicker, the title and the headnote hang below the painting.
const opener = { enabled: true, slot: { elements: [
  // An image element draws a resource without number or caption. It hangs from the
  // trim's corner, over the top margin and both side margins.
  { kind: 'image', id: 'headpiece', resourceId: 'tea-table',
    placement: { anchor: { to: 'page', edge: 'top-left' },
      size: { width: mm(TRIM_W) } } },
  // The numeral comes from the heading line,
  // # A Mad Tea-Party {num="VII" headnote="…" …}: the excerpt stands alone, so
  // {chapterNumber} would count its one heading and print 1.
  { kind: 'text', id: 'kicker', content: 'Chapter {attr.num}', fontFamily: LABEL,
    fontWeight: 600, fontSize: pt(9), letterSpacing: pt(2), textTransform: 'uppercase',
    color: col('jam'), align: 'left',
    placement: { anchor: { to: 'container', edge: 'top-left' },
      offset: { y: mm(HEADPIECE - TOP + 8) } } }, // 8 mm under the painting's foot
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY,
    fontSize: pt(40), lineHeight: 1.05, color: col('ink'), align: 'left', // wraps when longer
    placement: below('kicker', 2, 'fill') },
  // The drop cap opens the headnote, the editor's voice, italic and ragged; Carroll's
  // text opens in the flow, justified.
  { kind: 'text', id: 'headnote', content: '{attr.headnote}', fontFamily: TEXT,
    italic: true, fontSize: pt(HEADNOTE.size),
    lineHeight: pt(HEADNOTE.lead), color: col('ink'),
    align: 'left',
    dropCap: { lines: 2, fontFamily: DISPLAY, fontSize: dropSize(2), color: col('lawn'),
      gap: mm(1.5) },
    placement: below('title', 5, mm(TEXT_W)) },
  // The note on this edition stands in the channel, level with the headnote's top.
  { kind: 'text', id: 'edition-label', content: 'This edition', fontFamily: LABEL,
    fontWeight: 600, fontSize: pt(8.5), letterSpacing: pt(0.3), color: col('muted'),
    align: 'left', placement: { anchor: { to: '#headnote', edge: 'right-of' },
      offset: { x: layout.gutterWidth }, size: { width: mm(SIDE_W) } } },
  { kind: 'text', id: 'edition', content: '{attr.source}', fontFamily: TEXT,
    fontSize: pt(7.5), lineHeight: pt(10), color: col('muted'), align: 'left',
    placement: { anchor: { to: '#edition-label', edge: 'below' }, offset: { y: mm(0.8) },
      size: { width: mm(SIDE_W) } } },
] } };

The heading’s design slot spans the page so that the painting can reach the trim. The kicker, the title and the headnote hang below the painting, and the opener reserves down to the lowest of them, rounded up to the grid; the heading’s default bottom margin adds one blank line. With a four-line headnote the text starts on line 23, and a fifth line would move it to line 24. The numeral, the headnote and the note on this edition come from heading attributes, {num="VII" headnote="…" source="…"}. The numeral comes from there because {chapterNumber} would print 1 in an excerpt that is a document of its own. The drop cap opens the editor’s headnote, set ragged in italic, and Carroll’s text starts justified in the flow below it. dropSize() sizes the initial so that its top lines up with the capitals of the headnote’s first line.

#6 · Colour each gloss by what it explains

script.js · lines 16–30in full code
const palette = {
  ink: '#1f1b1a', // text: a warm near-black
  lawn: '#1e6f6b', // glosses on words and jokes, the drop cap
  jam: '#b23a48', // glosses on history, the kicker
  muted: '#6e645b', // running heads, the note on this edition
  paper: '#f8f3e6', // the page, and the tablecloth
};
// col(id): a colour linked to its palette entry, with the entry's hex beside the id.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const entry = (id, hex, name = id) => ({ id, name, value: { hex, model: 'hex' } });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => entry(id, hex)),
  // The engine's defaults link to 'main-color': aimed at the green, nothing prints blue.
  entry('main-color', palette.lawn, 'lawn (defaults)'),
];

Lawn green marks glosses on words, sayings and jokes, and jam red marks people, dates and the history of the text. A new value for jam in the same palette object recolours the glosses on history, their letters and the kicker in one edit; the watercolour above them was chosen for the same lawn green and jam red.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 032 · Annotated classic with margin glosses ════════════
// https://postext.dev/en/cookbook/annotated-classic-glosses
// Code: MIT · Text: Lewis Carroll (PD), glosses (CC BY 4.0) · Headpiece: diffusion models
// Fonts: Unna, Rozha One, Cormorant SC (SIL OFL 1.1) · Needs postext ≥ 1.28.0
// The mad tea-party as an annotated edition: the text keeps to one column, and its glosses stand
// in the outer margin beside the lines they explain, changing sides with the spread.
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en')
const RECIPE = 'annotated-classic-glosses';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a lawn green and a jam red on cream paper
const palette = {
  ink: '#1f1b1a', // text: a warm near-black
  lawn: '#1e6f6b', // glosses on words and jokes, the drop cap
  jam: '#b23a48', // glosses on history, the kicker
  muted: '#6e645b', // running heads, the note on this edition
  paper: '#f8f3e6', // the page, and the tablecloth
};
// col(id): a colour linked to its palette entry, with the entry's hex beside the id.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const entry = (id, hex, name = id) => ({ id, name, value: { hex, model: 'hex' } });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => entry(id, hex)),
  // The engine's defaults link to 'main-color': aimed at the green, nothing prints blue.
  entry('main-color', palette.lawn, 'lawn (defaults)'),
];
// #endregion
const [TEXT, DISPLAY, LABEL] = ['Unna', 'Rozha One', 'Cormorant SC'];
const LEAD = 14; // body leading in pt: the grid of every page

// #region answer: a float-only channel at the fore-edge, and two gloss styles for it
const layout = {
  layoutType: 'oneAndHalf', // one text column and a narrower side column
  sideColumnPercent: 26, // of the 127 mm between the margins: a 33 mm channel
  sideColumnRole: 'floats', // no text runs in it: it holds side boxes and figures
  sideColumnSide: 'outer', // at the fore-edge, which mirrored margins move page by page
  gutterWidth: mm(4.5), // the text column keeps 127 − 33 − 4.5 = 89.5 mm
};
// A gloss is :::callout{type="note" span="side" title="a · …"} in the Markdown.
// span="side" moves it out of the flow into the channel, level with the block after
// the fence, so the fence goes just before the paragraph that carries its letter.
// Glosses never float. One that meets the gloss above stacks under it. One that would
// run past the column's foot slides up, as far as the gloss above allows, until its
// foot sits on the foot; if it still does not fit, it waits for the next page

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 glosses on the right of every page

For an edition read one page at a time on screen, turn mirroring off: 'outer' then means the right-hand edge of every page, and the running heads keep their places, since they are anchored to the trim.

-    mirror: true } };
+    mirror: false } };

#Send the long notes to the foot of the page

Write a note too long for the margin as a footnote, [^1] in the text and its [^1]: definition under the paragraph: Postext sets it at the foot of the text column, 89.5 mm wide under a short rule, and the glosses keep the channel. Footnotes at the foot of the column that cites them styles those notes.

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 →

  • Glosses stack in the order of the Markdown, one under another, so a long gloss pushes the next one down. On page 81 both letters fall in the second line of the first paragraph: gloss a starts level with the paragraph and gloss b below it, five lines under its letter. Where letters come close together, keep the glosses short.

Credits

Text
  • Alice’s Adventures in Wonderland (1865), the opening of chapter VII, “A Mad Tea-Party” · Lewis Carroll · public domain
  • The headnote, the eight glosses and the note on this edition · Ignacio Ferro · CC BY 4.0
Images
  • The tea-table seen from above, a watercolour · Generated With Diffusion Models · original
Fonts
Unna (SIL OFL 1.1) · Rozha One (SIL OFL 1.1) · Cormorant SC (SIL OFL 1.1)
Sandbox