Skip to main content
Recipe number 80

Cookbook · Chapter 2 · Type & text

A vertical reader with zhuyin to the right

A Taiwan school reader set down the page: {守株|ㄕㄡˇ|ㄓㄨ} sets a zhuyin column right of each character, with pictures and notes in an upper tier.

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

pp. 86–87 · 1–2 of 4

  • Trim 184 × 260 mm
  • Column and a half, 11.3 mm gutter
  • Iansui 16/32
  • Noto Sans TC
  • Noto Serif TC
  • 4 pages
  • Level
  • Postext 1.65.0
  • Laid out in 124 ms
  • 184 lines of code

In short

A school reading book from Taiwan, printed in columns from top to bottom. Each Chinese character has a small sound guide beside it, so children can read words they have not learned yet.

What you'll build

Lesson 12 of 國語 book 9, an invented fifth-grade reader from Taiwan: two fables from the Han Feizi, the farmer of Song who waits by a stump for another hare and the man of Zheng who trusts his measure more than his feet. Taiwan's readers are set vertically, in a Kai hand, with the zhuyin of every character in a column to its right, so a child can read a character before learning it. The lesson opens on a spread bound on the right. Above, a tier holds the pictures, the notes, the author and the new characters; below, the lesson runs in 16 pt Iansui, 23 characters to the line. The Latin-script counterpart is the textbook with a margin column, whose float-only side column is the upper tier here, turned a quarter.

This recipe answers

  • How do I set zhuyin beside every character of a vertical Chinese text?
  • How do I set a Chinese book vertically, bound on the right?

The short answer

script.js · lines 35–56in full code
const layout = {
  writingMode: 'vertical-rl', // lines run down the page, read from the right; bound on the right
  layoutType: 'oneAndHalf', // two tiers: the text below, pictures and notes above
  sideColumnRole: 'floats', sideColumnSide: 'left', // 'left' is the top tier in vertical text
  sideColumnPercent: 34,
  gutterWidth: pt(2 * SIZE),
};
const cjk = {
  // The lower tier: 23 characters down, 13 lines across the page.
  grid: { enabled: true, charsPerLine: 23, linesPerPage: 13 },
  // Readings at half the text size; zhuyin sets its symbols at 60 % of that, 0.3 em,
  // so three symbols fit beside one character, and beside each of two in a row.
  ruby: { fontFamily: ZHUYIN, fontSize: em(0.5) },
};
// The line pitch is twice the size: a gap of one em, which the zhuyin and its tone
// marks half fill. clreq asks for 1.5 em; one em keeps 13 lines of 23 on the page.
const LINE = 2 * SIZE;
const bodyText = {
  fontFamily: KAI, fontSize: pt(SIZE), lineHeight: pt(LINE), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  textAlign: 'justify', firstLineIndent: em(2), indentAfterHeading: true,
};

Vertical text with a zhuyin column right of every character

Ingredients

Type
Iansui, LXGW WenKai TC, Noto Serif TC, Noto Sans TC (SIL OFL 1.1)
Assets
  • plate-1-1500.jpg
  • plate-2-1500.jpg
  • The farmer waiting by the stump, a brush painting (Generated With Diffusion Models, original)
  • The man of Zheng hurrying home from the shoe stall, a brush painting (Generated With Diffusion Models, original)

Method

#1 · A zhuyin column beside each character

The code is the short answer above. {宋人|ㄙㄨㄥˋ|ㄖㄣˊ} gives each character its own reading, one per |; punctuation stays outside the braces, so 。and , get none. In vertical text a reading in bopomofo goes right of the column, its symbols stacked, the tone mark right of the last one and the dot of the neutral tone above the first. At half the text size, cjk.ruby.fontSize sets the symbols at 0.3 em, so three symbols fit beside a character, and two such readings in a row, as in 就像, keep at least a quarter of a symbol apart without widening either character; at 0.6 em ㄇㄧㄥˊ is taller than 明 and spaced 明明 apart. The 32 pt line pitch leaves a gap of one em, which the zhuyin and its tone marks half fill. clreq asks for 1.5 em when zhuyin stands between vertical lines; that is a 40 pt pitch and ten lines to the page, so this page keeps one em for 13 lines of 23, and each reading stays about 8 pt clear of the line beside it.

#2 · Pictures and notes in the upper tier

script.js · lines 60–74in full code
const resourceTypes = [{ id: 'plate', name: '插圖', shortLabel: '圖', numberingTemplate: '{n}',
  resetOn: 'never', counterFormat: 'decimal', captionPrefix: '' }]; // no prefix, no caption
const box = (id, title, body) => ({ id, title, background: col('tint'),
  padding: { top: mm(3), right: mm(3), bottom: mm(3), left: mm(3) },
  titleStyle: { fontFamily: HEI, fontSize: pt(11), fontWeight: 700, color: col('accent') },
  body: { color: col('ink'), firstLineIndent: pt(0), textAlign: 'left', boldColor: col('ink'),
    italicColor: col('ink'), ...body } });
// Zhuyin is 0.3 em of the text it reads: at 13 pt the notes' readings are 3.9 pt.
const calloutStyles = [ // fenced :::callout{type="notes" span="side"} in the text
  box('notes', '注釋', { fontFamily: MING, fontSize: pt(13), lineHeight: pt(24) }),
  box('author', '作者', { fontFamily: MING, fontSize: pt(13), lineHeight: pt(24),
    textAlign: 'justify', firstLineIndent: em(2) }),
  box('chars', '生字', { fontFamily: KAI, fontSize: pt(22), lineHeight: pt(40),
    textAlign: 'center' }),
];

In vertical text the columns of a oneAndHalf layout are tiers, and sideColumnSide: 'left' puts the float-only one on top. ::resource{id="plate-1"} in the text sends the first picture there; the plate type has no caption prefix and the pictures no caption, so nothing prints under them. A box fenced with span="side" lands in the tier from the line where it is fenced, and its text runs down the tier. The notes of both fables are one box, numbered through the lesson and fenced after the first original, which ends on page 86: they fill the tier of page 87, so both fables' notes lie on the spread that holds their originals. Zhuyin is 0.3 em of the text it reads, and cjk.ruby is one setting for the book, so the notes and the author box are set at 13 pt to keep their readings at 3.9 pt.

#3 · Four faces, each loaded with its own text

script.js · lines 270–289in full code
// {株|ㄓㄨ}: the characters are the text, the readings go to the zhuyin face.
const BOXES = /^:::callout\{type="(?:notes|author)"[^}]*\}\n([\s\S]*?)^:::$/gm;
const bases = (md) => md.replace(/\{([^|{}]+)((?:\|[^|{}]+)+)\}/g, '$1');
const readings = [...markdown.matchAll(/\{[^|{}]+((?:\|[^|{}]+)+)\}/g)].map((m) => m[1]).join('');
await loadFonts(FONTS, markdown);
await loadCjkFonts({ [KAI]: ['400'] }, bases(markdown.replace(BOXES, '')), { vertical: true });
const notesText = [...markdown.matchAll(BOXES)].map((m) => m[1]).join('\n');
await loadCjkFonts({ [MING]: ['400'] }, bases(notesText), { vertical: true });
await loadCjkFonts({ [ZHUYIN]: ['400'] }, readings.replaceAll('|', ''), { vertical: true });
await loadCjkFonts({ [HEI]: ['400', '700'] }, LABELS, { vertical: true });
await Promise.all(Object.values(plates).map((fileId) => loadImage(fileId, asset(fileId))));
// Lesson 12 of a reader: page 86 is a verso, so the lesson opens on a spread.
const continuation = { pageIndexOffset: 1, pageNumbering: { startAt: 86 } };
const doc = await withLoadedFonts(
  () => buildDocument({ markdown, resources, continuation }, config()),
  { ...kitFonts(FONTS), text: markdown });
showBook(doc, { title: t({ en: 'A vertical reader with zhuyin',
  es: 'Un libro de lectura vertical con zhuyin' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: cjkPdfProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

The lesson is in Iansui, a Kai hand drawn from Klee One to Taiwan's standard character forms, the ones the children learn to write. The readings are in LXGW WenKai TC, whose neutral-tone dot stays round at 4.8 pt, the notes in Noto Serif TC and the labels in Noto Sans TC. Each face loads the files that hold the characters it sets: the readings are split from their characters, and the boxes of notes go to the Ming face alone. vertical: true adds the vertical forms, so 「」 and 、 stand as they should down the column. pageIndexOffset: 1 makes page 86 a verso, so the lesson opens on a spread.

#4 · The tab and the folios on the outer edge

script.js · lines 78–103in full code
// The verso lies on the right of the spread, so even pages carry both at the right edge.
const tab = (parity, edge) => [
  { kind: 'box', id: `tab-${parity}`, parity, pages: 'all',
    placement: { anchor: { to: 'page', edge }, offset: { y: mm(24) },
      size: { width: mm(9), height: mm(64) } }, style: { backgroundColor: col('accent') } },
  { kind: 'text', id: `unit-${parity}`, content: '第三單元 寓言故事', parity, pages: 'all',
    writingMode: 'vertical-rl', fontFamily: HEI, fontSize: pt(9), fontWeight: 700,
    color: col('paper'), align: 'center', verticalAlign: 'middle',
    placement: { anchor: { to: `#tab-${parity}`, edge: 'align-top' },
      size: { width: mm(9), height: mm(64) } } },
];
const foot = (id, parity, edge, x, content, extra = {}) => ({
  kind: 'text', id, content, parity, pages: 'all', fontFamily: HEI, fontSize: pt(8),
  color: col('muted'), placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(-9) } },
  ...extra,
});
const folio = { fontSize: pt(9), fontWeight: 700 };
const header = { elements: [...tab('even', 'top-right'), ...tab('odd', 'top-left')] };
const footer = {
  elements: [
    foot('folio-even', 'even', 'bottom-right', -16, '{pageNumber}', folio),
    foot('book', 'even', 'bottom-right', -26, '國語 第九冊'),
    foot('folio-odd', 'odd', 'bottom-left', 16, '{pageNumber}', folio),
    foot('lesson', 'odd', 'bottom-left', 26, '{chapterNumber} {chapterTitle}'),
  ],
};

In a book bound on the right the verso lies on the right of the spread, so even pages carry the unit's tab and the folio at the right edge and odd pages at the left. The tab is a box with a text element over it; writingMode: 'vertical-rl' on the element sets 第三單元 寓言故事 down the tab, while the folios and the foot lines stay horizontal. The lesson and fable numbers come from the headings' numberingTemplate (第{1:一}課 and {2:一}, an ideographic space as numberSeparator, {startAt=12} on the lesson), set apart from the title so the zhuyin of 寓 stays over 寓; the odd foot line prints {chapterNumber} {chapterTitle}, since {chapterTitle} leaves the number out.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 080 · A vertical reader with zhuyin to the right ═════════
// https://postext.dev/en/cookbook/zhuyin-vertical-reader
// Code: MIT · Text: Han Feizi, zh.wikisource (CC BY-SA 4.0) · Pictures: diffusion models
// Fonts: Iansui, LXGW WenKai TC, Noto Serif TC, Noto Sans TC (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, 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 = 'zhuyin-vertical-reader';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: semantic colours, every one linked by id
const palette = {
  ink: '#2b2520', // text and zhuyin
  accent: '#b83f28', // lesson title, labels, the unit's tab (4.9:1 on the tint)
  tint: '#f7efdf', // the boxes of the upper tier
  muted: '#72675b', // lead, folios, colophon
  paper: '#ffffff', // the lettering on the tab
};
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' } })),
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion
const KAI = 'Iansui'; // 楷: the lesson, drawn to Taiwan's standard forms (為, not 爲)
const ZHUYIN = 'LXGW WenKai TC'; // the readings: a round dot for the neutral tone
const MING = 'Noto Serif TC'; // 明: notes and the author box
const HEI = 'Noto Sans TC'; // 黑: labels, folios, the tab
const SIZE = 16; // the text size (三號)

// #region answer: vertical text with a zhuyin column right of every character
const layout = {
  writingMode: 'vertical-rl', // lines run down the page, read from the right; bound on the right
  layoutType: 'oneAndHalf', // two tiers: the text below, pictures and notes above
  sideColumnRole: 'floats', sideColumnSide: 'left', // 'left' is the top tier in vertical text
  sideColumnPercent: 34,
  gutterWidth: pt(2 * SIZE),
};
const cjk = {
  // The lower tier: 23 characters down, 13 lines across the page.
  grid: { enabled: true, charsPerLine: 23, linesPerPage: 13 },
  // Readings at half the text size; zhuyin sets its symbols at 60 % of that, 0.3 em,
  // so three symbols fit beside one character, and beside each of two in a row.
  ruby: { fontFamily: ZHUYIN, fontSize: em(0.5) },
};

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

Some readers print the readings lighter than the text, so the characters come forward.

-  ruby: { fontFamily: ZHUYIN, fontSize: em(0.5) },
+  ruby: { fontFamily: ZHUYIN, fontSize: em(0.5), color: col('muted') },

#Set the readings over horizontal text

The pinyin primer sets one syllable over each character across the page, as mainland and Hong Kong first readers do.

Pitfalls

Pitfall

Readings print in the text, not in designs, captions or cells

Ruby readings are drawn in paragraphs, headings, list items, quotations and boxes. A design text element (an opener, a running head, a badge), a caption, a footnote and a table cell print the base characters without their readings. A title that needs its pinyin is a heading without a design of its own: draw what surrounds it (a band, a lesson number) with the design of the heading before it, whose elements with reserve: false paint under the text of a span: 'page' opener. Ruby: pinyin and zhuyin readings →

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 →

  • Take the readings from Taiwan's dictionary. Tools built on mainland dictionaries, pypinyin among them, give 度 duó, 寧 nìng, 時候 shíhou and 市場 shìchǎng; the Ministry of Education's Revised Mandarin Chinese Dictionary, which Taiwan's readers follow, reads ㄉㄨㄛˋ, ㄋㄧㄥˊ, ㄕˊ ㄏㄡˋ and ㄕˋ ㄔㄤˊ, and sets 故事, 家裡 and 過來 with a neutral second syllable. moedict.tw serves it word by word. It keeps 一 and 不 in their own tone, and so does this lesson.

  • Draw a few characters in each face before you mix them. LXGW WenKai TC follows the inherited forms and draws 為 (U+70BA) as 爲, so a lesson in it printed 爲宋國笑 in the text and 為宋國笑 in the Ming note on the same spread. Iansui draws the standard 為.

  • Iansui has one weight. The headings stand out by size and the idiom headwords by colour: the idiom style sets boldFontWeight: 400 with the accent as boldColor, so **…** changes the colour and not the face.

Credits

Text
Images
  • The farmer waiting by the stump, a brush painting · Generated With Diffusion Models · original
  • The man of Zheng hurrying home from the shoe stall, a brush painting · Generated With Diffusion Models · original
Fonts
Iansui (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1) · Noto Serif TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1)
SandboxPDF