Skip to main content
Recipe number 78

Cookbook · Chapter 6 · Boxes & notes

Red-ink commentary in the line and the head margin

A vertical Chinese commentary page: the manuscript's side comments folded into two red rows inside the line, head-margin comments in a tier above the text.

On this page
Output
Canvas · PDF
Postext
Tested with Postext 1.65.0
Needs ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Licence
Updated 11 Oct 2026
Code MIT · Text CC BY 4.0

pp. 四–五 · 4–5 of 6

  • Trim 184 × 260 mm
  • Column and a half, 8.5 mm gutter
  • Noto Serif TC 12/21
  • LXGW WenKai TC
  • Noto Sans TC
  • 6 pages
  • Level
  • Postext 1.65.0
  • Laid out in 101 ms
  • 156 lines of code

In short

Six pages of a classic Chinese novel, printed in columns that read from top to bottom. A reader's old notes in red appear inside the lines and in a strip above the text.

What you'll build

The opening of chapter 1 of the Jiaxu manuscript of The Story of the Stone, the copy that carries Zhiyan Zhai's commentary, reset as six pages of a commentary edition on a 16开 page, 184 × 260 mm, set vertically and bound on the right. Cao Xueqin's text runs in Noto Serif TC, 36 characters down each column and 18 columns to the page. The manuscript writes the excerpt's 61 side comments (側批) in red beside the columns. Postext sets nothing between two columns, so this edition moves each one into the line, folded into two vermilion rows at half the size right after the words it glosses, the way printed commentary editions set their 雙行夾批. The ten head-margin comments (眉批) stand in red Kai in a 42 mm tier above the text, over the passage they discuss, so a reader follows the text and the commentary in one pass.

This recipe answers

  • How do I set a commentary edition: small two-line notes inside the line and comments in the head margin?
  • How do I set a Chinese book vertically, bound on the right?

The short answer

script.js · lines 38–65in full code
const layout = {
  writingMode: 'vertical-rl', // columns down the page, read from the right; bound on the right
  layoutType: 'oneAndHalf', // a text tier and a narrow tier for the comments
  sideColumnRole: 'floats', // no text runs into it: only boxes fenced with span="side"
  sideColumnSide: 'left', // in vertical text 'left' is the top tier: the head margin (天頭)
  sideColumnPercent: 19, // the grid rounds it to 10 characters of the body, 42 mm
  gutterWidth: mm(8), // rounded to 2 characters
  columnRule: { enabled: true, lineWidth: pt(0.5), color: col('rule') },
};
const cjk = {
  grid: { enabled: true, charsPerLine: 36, linesPerPage: 18 }, // 版心: 36 字 × 18 行
  // :warichu[…] folds a side comment into two rows at half the body size, in red
  // and with no brackets, as the manuscripts write their 雙行夾批.
  warichu: { color: col('vermilion') },
};
// A 眉批 is :::callout{type="meipi" span="side"}: span="side" sends it to the head
// margin, level with the column the text has reached at its fence, so the fence goes
// just before the passage it discusses (gotcha: side-box-starts-at-fence).
const meipi = {
  id: 'meipi', backgroundEnabled: false,
  border: { enabled: false }, stripe: { enabled: false },
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  // 17 characters of 7 pt down the 120 pt tier, a column every 10 pt. The next comment
  // starts on a text column at least one body column (21 pt) further on, whatever the margin.
  snapToGrid: false, marginBottom: pt(0),
  body: { fontFamily: KAI, fontSize: pt(7), lineHeight: pt(10), color: col('vermilion'),
    textAlign: 'left', firstLineIndent: pt(0) },
};

Side comments inside the line, head-margin comments above it

Ingredients

Type
Noto Serif TC, LXGW WenKai TC, Noto Sans TC (SIL OFL 1.1)
Assets
None: every picture is drawn in code

Method

#1 · Turn the side column into the head margin

The code is the short answer above. A vertical page is a horizontal page turned a quarter turn, so the side column of a column-and-a-half layout becomes a tier across the page, and sideColumnSide: 'left' puts that tier at the head (Vertical writing). The character grid rounds sideColumnPercent: 19 to 10 characters of the body, 120 pt, and the gutter to two; the column rule becomes the hairline between the comments and the text. The comment style has no box: 7 pt Kai, 17 characters to a column, a size at which none of the ten comments ends on a column of one character, and snapToGrid: false so the comments stack at their own 10 pt pitch instead of the body's 21 pt.

Both kinds of comment are marked where the manuscript has them. A side comment is a :warichu[…] span, which cjk.warichu colours; a head-margin comment is a box fenced with span="side" just before the passage it discusses:

:::callout{type="meipi" span="side"}
妙!自謂落墮情根,故無補天之用。
:::
 
原來女媧氏煉石補天之時,:warichu[補天濟世,勿認真,用常言。]于大荒山:warichu[荒唐也。]…

#2 · Set the chapter's number and couplet down the first columns

script.js · lines 69–81in full code
const opener = { enabled: true, minHeight: mm(46), slot: { elements: [
  { kind: 'text', id: 'book', content: '{title}', fontFamily: HEI, fontWeight: 500,
    fontSize: pt(10), letterSpacing: pt(3), color: col('vermilion'), align: 'left',
    placement: { anchor: { to: 'container', edge: 'top-left' } } },
  { kind: 'text', id: 'number', content: '{titleText}', fontFamily: SONG, fontWeight: 700,
    fontSize: pt(30), letterSpacing: pt(6), color: col('ink'), align: 'left',
    placement: { anchor: { to: '#book', edge: 'below' }, offset: { x: em(2), y: mm(4) } } },
  ...['a', 'b'].map((half, i) => ({ kind: 'text', id: `couplet-${half}`,
    content: `{attr.${half}}`, fontFamily: SONG, fontSize: pt(15), letterSpacing: pt(3),
    color: col('ink'), align: 'left',
    placement: { anchor: { to: i ? '#couplet-a' : '#number', edge: 'below' },
      offset: { x: i ? pt(0) : em(4), y: mm(i ? 1.5 : 4) } } })),
] } };

On a vertical page an opener is laid out in the flow's frame, so its text runs down, below means to the left and an x offset moves an element down the column. The book's title comes first in red Hei, then 第一回 at 30 pt, lowered two of its own characters, then the two halves of the couplet from the heading attributes {a="…" b="…"}, lowered again, so the number and the couplet step down the page as in a printed 回目. minHeight: mm(46) keeps a clear column between the couplet and the text.

#3 · Run the heads down the fore-edge

script.js · lines 85–96in full code
// 'outer' is the margin away from the spine: a recto's left, a verso's right.
const edge = (id, content, edgeOf, y, extra = {}) => ({ kind: 'text', id, content,
  writingMode: 'vertical-rl', fontFamily: HEI, fontWeight: 500, fontSize: pt(9.5),
  letterSpacing: pt(2), color: col('muted'), overflow: 'clip', align: 'left',
  placement: { anchor: { to: 'outer', edge: edgeOf }, offset: { y: em(y) } }, ...extra });
const header = { elements: [
  // Four characters below the head: the book on a verso, the chapter on a recto,
  // never on the opener.
  edge('head-verso', '{title}', 'top', 4, { pages: 'body', parity: 'even' }),
  edge('head-recto', '{chapterTitle}', 'top', 4, { pages: 'body', parity: 'odd' }),
  edge('folio', '{pageNumber}', 'bottom', -5), // 一, 二, 三…: page.pageNumbering below
] };

These are the fore-edge heads of Vertical text elements: anchor.to: 'outer' is the margin away from the spine, the left of a recto and the right of a verso in a right-bound book, and writingMode: 'vertical-rl' sets the text down the page. The type area here includes the comment tier, so "four characters below the head" is measured from the top of the red comments. trad-chinese-informal prints the folios 一 to 六.

#4 · Load each voice with the text it sets

script.js · lines 246–258in full code
// Song sets the whole sample and its bold only 第一回, Kai the head-margin comments and
// the edition's note, Hei the running heads, the folios and the colophon
// (gotcha: cjk-fonts-slices).
const blocks = (style) => [...markdown.matchAll(
  new RegExp(`:::(?:callout|paragraphs)\\{[^}]*"${style}"[^}]*\\}\\n([^]*?)\\n:::`, 'g'))]
  .map((m) => m[1]).join('');
const numerals = '一二三四五六七八九十';
await loadFonts(FONTS, markdown);
await loadCjkFonts({ [SONG]: ['400'] }, markdown, { vertical: true });
await loadCjkFonts({ [SONG]: ['700'] }, '第一回'); // the bold weight sets three characters
await loadCjkFonts({ [KAI]: FONTS[KAI] }, blocks('meipi') + blocks('note'), { vertical: true });
await loadCjkFonts({ [HEI]: FONTS[HEI] }, `脂硯齋重評石頭記第一回${numerals}${blocks('colophon')}`,
  { vertical: true });

Fontsource serves each Chinese face as about a hundred files per weight. Song sets the whole sample in its regular weight and only 第一回 in bold, Kai only the head-margin comments and the edition's note, and Hei only the heads, the folios and the colophon, so each call fetches the files its own characters need. vertical: true also loads each face's vertical punctuation for the canvas.

#5 · Two inks

script.js · lines 18–31in full code
const palette = {
  ink: '#231d18', // the text: a warm black
  vermilion: '#b0362a', // 朱: every comment, the chapter's kicker; 5.5 : 1 on the paper
  rule: '#b9a78f', // the line under the head margin
  muted: '#6f6356', // folios, the colophon
  paper: '#f7f1e3',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to main-color: aimed at the vermilion, nothing prints blue.
  { id: 'main-color', name: 'vermilion (defaults)',
    value: { hex: palette.vermilion, model: 'hex' } },
];

The page prints in two colours, as the manuscript was written: a warm black for the text and a vermilion for every comment, the chapter's kicker and nothing else. The vermilion reads at 5.5 : 1 on the paper, enough for the 6 pt rows of the side comments. main-color points at it, so a default the config does not restate prints red, never blue.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 078 · Red-ink commentary in the line and the head margin ═══
// https://postext.dev/en/cookbook/red-ink-commentary
// Code: MIT · Text: 脂硯齋重評石頭記, Jiaxu manuscript, Wikisource (CC BY-SA 4.0) · Pictures: none
// Fonts: Noto Serif TC, LXGW WenKai TC, Noto Sans TC (SIL OFL 1.1) · Needs postext ≥ 1.28.0
// The first chapter of the Stone as a commentary edition: the text set vertically, the
// comments the manuscript writes beside the columns folded into two small red rows inside
// the line, the head-margin comments in red Kai above the columns they gloss.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'red-ink-commentary';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: black ink and vermilion on a warm paper
const palette = {
  ink: '#231d18', // the text: a warm black
  vermilion: '#b0362a', // 朱: every comment, the chapter's kicker; 5.5 : 1 on the paper
  rule: '#b9a78f', // the line under the head margin
  muted: '#6f6356', // folios, the colophon
  paper: '#f7f1e3',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to main-color: aimed at the vermilion, nothing prints blue.
  { id: 'main-color', name: 'vermilion (defaults)',
    value: { hex: palette.vermilion, model: 'hex' } },
];
// #endregion
const [SONG, KAI, HEI] = ['Noto Serif TC', 'LXGW WenKai TC', 'Noto Sans TC']; // 宋, 楷, 黑
const BODY = 12; // pt, 小四: the notes fold to two rows of 6 pt in the same em
const LEAD = 21; // pt between columns, 1.75 × the body

// #region answer: side comments inside the line, head-margin comments above it
const layout = {
  writingMode: 'vertical-rl', // columns down the page, read from the right; bound on the right
  layoutType: 'oneAndHalf', // a text tier and a narrow tier for the comments
  sideColumnRole: 'floats', // no text runs into it: only boxes fenced with span="side"
  sideColumnSide: 'left', // in vertical text 'left' is the top tier: the head margin (天頭)
  sideColumnPercent: 19, // the grid rounds it to 10 characters of the body, 42 mm
  gutterWidth: mm(8), // rounded to 2 characters
  columnRule: { enabled: true, lineWidth: pt(0.5), color: col('rule') },
};
const cjk = {
  grid: { enabled: true, charsPerLine: 36, linesPerPage: 18 }, // 版心: 36 字 × 18 行

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

For a single-colour printing, set the notes in black between brackets and the head-margin comments in the muted ink; the brackets are set at the text size before a note's first row and after its last.

-  warichu: { color: col('vermilion') },
+  warichu: { color: col('ink'), open: '〔', close: '〕' },
-  body: { fontFamily: KAI, fontSize: pt(7), lineHeight: pt(10), color: col('vermilion'),
+  body: { fontFamily: KAI, fontSize: pt(7), lineHeight: pt(10), color: col('muted'),

#Compare it with a Latin-script edition

The same technique on a horizontal page is the annotated classic with margin glosses: the side column stands at the fore-edge (sideColumnSide: 'outer'), and each gloss sits beside the paragraph it explains instead of above it.

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

In vertical text the side column is a tier, and 'left' is the top one

With layout.writingMode 'vertical-rl' the page is a horizontal page turned a quarter turn, so the side column of a oneAndHalf layout becomes a tier across the page: sideColumnSide 'left' puts it at the head, the place of head-margin comments (眉批), and 'right' at the foot. 'outer' and 'inner' read as 'right' and 'left' (a tier has no outer edge), so the 'outer' of a textbook's margin column sends the notes to the foot. sideColumnPercent is a share of the page's height. Margin column for floats →

Pitfall

Chinese faces load by slices, through the cjk block

Fontsource serves a Chinese, Japanese or Korean family as about a hundred files per weight, each covering a range of characters. loadFonts fetches only the latin file, so on screen the Han characters come from a system face and measure wrong, and fontsourceProvider hands the PDF that latin file, which prints them as empty boxes. List the cjk kit block, call loadCjkFonts(FONTS, markdown) after loadFonts (once per voice, with the text it sets, when the book uses several CJK faces) and give renderToPdf fontProvider: cjkPdfProvider: both take the files that hold the text's characters. Chinese, Japanese and Korean fonts →

Pitfall

A right-bound book shows its spreads with showBook

In a book bound on the right (Arabic, Hebrew or Persian text, vertical Chinese, or page.binding 'right') page 1 is still the recto, but it lies on the left of the spine, and the pairs read [3 | 2]. showPages lays every book out left-bound; showBook from the book block (the cjk block carries the same function) reads doc.binding and mirrors the pairs. capture.hero still names a spread in reading order, [verso, recto]: [2, 3]. Books bound on the right →

Pitfall

Tag the document zh-Hans or zh-Hant, not with LANG

A recipe's editions are en and es, but a Chinese sample is Chinese in both: `locale: LANG` would tag it English or Spanish, hyphenate its Latin words, label its figures Figure or Figura and give the PDF the wrong language. From postext 1.30 the tag is also the language the text is shaped in (measured, painted and embedded), so under an English or Spanish tag a Chinese face sets its digits and the punctuation it shares with Latin text in other forms, and the lines break elsewhere. Write the tag yourself: 'zh-Hans' (mainland conventions: GB line breaking, Kaiming punctuation) or 'zh-Hant' (Taiwan: full-width centred punctuation); 'zh-HK' for Hong Kong. A bare 'zh' reads as Simplified, mainland. A Japanese sample takes 'ja' (gotcha ja-locale-tag). Chinese line breaking →

  • A head-margin comment stands level with the column the text has reached at its fence, so the fence goes just before the passage it discusses; fenced after it, the comment starts beside the next paragraph. A fence sits between two blocks, never inside a paragraph, so where the manuscript comments on a phrase deep inside a long one, this edition breaks the paragraph there: before 石頭聽了, before 廟傍住着, and once inside the stone's speech, before 竟不如我, where the new paragraph opens with 「 again as a quotation that runs over two paragraphs does.
  • The tier holds what its page holds. A comment too long for the rest of it moves back to the right until its last column meets the left edge of the text, and one that still does not fit waits for the next page, with every comment fenced after it. Each comment starts on a text column and leaves a body column clear after the one before it. The manuscript's three comments on the stone's speech take eleven columns of the tier: fenced before 今之人, where the transcription has them, the last of them, 斯亦太過, waited for page 5 and pushed the comments there one step on. This edition breaks the speech one sentence earlier, before 竟不如我, and all three stand on page 4.
  • The grid fills every page with its 18 columns without a setting: on a character grid avoidWidows is off by default, so a paragraph may open in the last column of a page. Turned on, it would move that paragraph on whole, the page would end a column short and a comment fenced before the paragraph would stay behind. avoidOrphans stays on, as a Chinese grid has it by default: a paragraph's last column alone at the head of a page (孤行) is what a Chinese editor avoids.
  • Two side comments written one after the other fold into rows that read as one note. The Markdown keeps an ideographic space (U+3000) between them.
  • Noto Serif TC has no glyph for some manuscript forms, such as 縂, 竒 and 数. The canvas fills them from a system face, and the PDF leaves them blank and lists them under C25. This edition sets their standard forms and keeps the variants the faces have.

Credits

Text
  • 脂硯齋重評石頭記 (The Story of the Stone, re-annotated by Zhiyan Zhai), Jiaxu manuscript (1754), chapter 1 from its opening to the Zhen household, with the commentary; Wikisource transcription, revision 2644544 · Cao Xueqin and Zhiyan Zhai; transcription by Wikisource editors · CC BY-SA 4.0
  • The note on this edition (本編說明) and the paragraph breaks added for the head-margin comments · Ignacio Ferro · CC BY 4.0
Fonts
Noto Serif TC (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1)
SandboxPDF