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
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
- Features
- Ruby: pinyin and zhuyin readingsVertical textBooks bound on the rightChinese, Japanese and Korean fontsChinese punctuation widthsCharacter gridColumn and a halfMargin column for floatsMargin notesChinese numeralsNumbered listsCustom resource typesCallout boxesParagraph stylesHeading stylesText, rules and boxes in page designsRunning heads and foliosPDF export
- Also uses
- Chinese line breakingHeading attributesNumbered headingsFigures exactly hereHeads by page roleFonts embedded in the PDFFigures and tables as resourcesNumbers upright in vertical textUnnumbered chapters
- Type
- Iansui, LXGW WenKai TC, Noto Serif TC, Noto Sans TC (SIL OFL 1.1)
- Assets
plate-1-1500.jpgplate-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
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
// {株|ㄓㄨ}: 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
// 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
// ═══ 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
#Print the zhuyin in a second colour
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
idiomstyle setsboldFontWeight: 400with the accent asboldColor, so**…**changes the colour and not the face.
Credits
- Recipe
- Ignacio Ferro
- Text
- Han Feizi, chapter 49, “Wu du” (The five vermin): the man of Song who waited by the stump · Han Fei; transcription and punctuation by Wikisource editors (爲 set as 為, the Taiwan standard form) · CC BY-SA 4.0
- Han Feizi, chapter 32, “Wai chu shuo zuo shang”: the man of Zheng who went to buy shoes · Han Fei; transcription and punctuation by Wikisource editors · CC BY-SA 4.0
- The zhuyin (checked against the Ministry of Education's Revised Mandarin Chinese Dictionary), the modern Chinese versions, the notes, the author box, the lead and the exercises, written for this recipe · Postext Cookbook · CC BY 4.0
- 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)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


