Skip to main content
Recipe number 83

Cookbook · Chapter 1 · Page & grid

Tang poems facing their English verse

Each Tang poem opens a tinted recto and Giles’s English the verso facing it: one heading style breaks to even pages, the other to odd ones.

On this page
Genre
Poetry
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 MIT

pp. 2–3 of 10

  • Trim 148 × 210 mm
  • 1 column
  • Noto Serif TC 10.5/16
  • LXGW WenKai TC
  • Noto Sans TC
  • Source Sans 3
  • Source Serif 4
  • 10 pages
  • Level
  • Postext 1.65.0
  • Laid out in 123 ms
  • 180 lines of code

In short

A small book of Chinese poems from the Tang dynasty, with an old English translation on the facing page. Each row of Chinese verse sits level with the English lines that translate it.

What you'll build

A small bilingual book of Tang poems, set the way parallel-text editions set a classic: the Chinese on the right-hand page, on a leaf tinted like old paper, and Herbert A. Giles’s rhymed English of 1901 on the left-hand page facing it. Four poems by Li Bai, Du Fu and Wang Wei each take a spread, titled in each language and signed with the poet’s name. The Chinese is set in LXGW WenKai, a Kai face drawn after the brush, two lines of verse to a row, so every row stands level with the two English lines that translate it. Glosses in the reader’s language sit at the foot of the Chinese page. Facing translation, stanza by stanza sets a Spanish poem beside its English on a single page; here each language has a page of its own.

This recipe answers

  • How do I set a poem and its translation on facing pages, with the original always on the recto?
  • How do I set poetry: one line per verse, stanza gaps, hanging indents for wrapped lines, no hyphenation?
  • How do I do footnotes?
  • How do I force a page or column break, and start every chapter on a right-hand page?

The short answer

script.js · lines 39–63in full code
const SINK = 6; // lines of LEAD under both titles, so the two poems start on the same line
const at = (y) => ({ anchor: { to: 'container', edge: 'top' }, offset: { y: mm(y) } });
// A title whose foot is 23 mm down at any size, and the poet's line under it at 24 mm.
const titled = (size, title, poet, under = []) => ({
  enabled: true, minHeight: pt(SINK * LEAD),
  slot: { elements: [...under,
    { kind: 'text', id: 'title', content: '{titleText}', fontSize: pt(size), lineHeight: 1.2,
      align: 'center', overflow: 'wrap', color: col('ink'),
      placement: at(23 - (size * 1.2 * 25.4) / 72), ...title },
    { kind: 'text', id: 'poet', align: 'center', overflow: 'wrap', color: col('seal'),
      placement: at(24), ...poet },
  ] },
});
// Each style breaks to its own side of the spread (gotcha: style-inherits-break).
const english = { id: 'en', breakBefore: { enabled: true, parity: 'even' }, // a verso
  advancedDesign: titled(19, { fontFamily: ROMAN, italic: true },
    { content: '{attr.kicker}', fontFamily: LABEL, fontSize: pt(7.5), fontWeight: 600,
      letterSpacing: pt(1.5), textTransform: 'uppercase' }) };
// The original on a tinted leaf: span 'page' lets the tint reach past the text column.
const chinese = { id: 'zh', span: 'page', breakBefore: { enabled: true, parity: 'odd' },
  advancedDesign: titled(28, { fontFamily: SERIF, fontWeight: 700, letterSpacing: pt(7) },
    { content: '{attr.poet}', fontFamily: HEI, fontSize: pt(9), letterSpacing: pt(1.5) },
    [{ kind: 'box', id: 'leaf', reserve: false, style: { backgroundColor: col('leaf') },
      placement: { anchor: { to: 'page', edge: 'top-left' },
        size: { width: 'fill', height: 'fill' } } }]) };

The English opens the next verso, the Chinese the recto that faces it

Ingredients

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

Method

#1 · A heading style for each side of the spread

The code is the short answer above. Every poem is two level-1 headings: # Night Thoughts {style="en" …} with Giles’s verse, then # 靜夜思 {style="zh" …} with the poem. The en style breaks to the next even page, a verso; the zh style to the next odd page, the recto that faces it. While each poem fits its page no blank page goes in; an English version that ran over would push its original to the following recto, behind a blank verso (Break before). Both designs reserve six lines of the grid, so the English and the Chinese start on the same line. The Chinese style has span: 'page' because its first element, a box the size of the page, is the tinted leaf, and a design kept in the column stops at the column’s foot (Span and advanced design).

Page 2: the English opens the verso six lines down, on the grid line where the Chinese opens on page 3.

#2 · A row of Chinese for two lines of English

script.js · lines 67–76in full code
// Each English poem is a :::verse block: a line of verse a line of Markdown, Giles's indents
// as two leading spaces (two ems: bodyText.verse.indentStep), a blank line between stanzas.
// The block is centred on its longest line in the 103.7 mm measure, so a short poem and a
// long one both sit in the middle.
const verse = { id: 'verse', fontFamily: ROMAN, fontSize: pt(BODY), lineHeight: pt(LEAD) };
const shi = { id: 'shi', fontFamily: KAI, fontSize: pt(SHI), lineHeight: pt(2 * LEAD),
  textAlign: 'left', firstLineIndent: pt(0), // two lines of verse to a row: 2 × LEAD
  // Five characters and a full-width mark, twice: 12 ems, centred in the 28 of the grid.
  // A fixed left edge, and the note numbers after each row's 。: every character keeps its column.
  indent: pt((CHARS * BODY - 12 * SHI) / 2) };

The Chinese rows have twice the leading of the English lines, 32 pt against 16, so a row of two five-character lines faces the couplet Giles makes of it. In the moonlight poem on pages 4 and 5 a blank line between the English stanzas and a :::space{lines=1} between the Chinese ones each leave one line, and its three stanzas stay level across the spread. The Chinese row starts 51 pt in, which centres its twelve ems in the 28 of the grid, and each note marker stands after its row’s 。, outside the twelve: inside the row it would push every character after it six tenths of an em to the right, out of line with the row below. Each English poem is a :::verse block, centred on its longest line, so no indent has to be measured. Giles indents every other line; the Markdown keeps his two spaces, which bodyText.verse.indentStep sets two ems deep.

#3 · Glosses at the foot of the Chinese page

script.js · lines 80–84in full code
const footnotes = { placement: 'column', numbering: 'page', // the page foot; ① again on each page
  numberFormat: 'circled-decimal', markerSize: em(0.6), fontSize: pt(8), lineHeight: pt(11),
  color: col('ink'), textAlign: 'left', spaceAbove: pt(LEAD), spaceBelowRule: pt(5),
  spaceBetween: pt(3), separator: { width: 0.12, lineWidth: pt(0.6), color: col('seal') },
  wordBreak: 'keep-all' }; // a reading a note quotes (山月, 看月光) is never broken

The glosses are footnotes, one to a row: 疑是地上霜。[^bed] closes the first row of the poem and [^bed]: … follows it, naming in bold each word it glosses, since the number no longer stands next to them. They are numbered as a Chinese book numbers its notes (页下注): circled numbers set on the baseline, counted from ① again on every page (numberFormat: 'circled-decimal', numbering: 'page'). In the verse the marker is set at six tenths of the poem’s size, markerSize: em(0.6), close to the size of the notes; at the foot of the page each note opens with its ① at the size of the note text (Footnotes). Notes are set in the body face, and this book’s body face is Noto Serif TC because a gloss mixes characters and pinyin; the Latin letters of Noto Serif TC come from Source Serif, which is why the English pages are set in Source Serif 4. The notes are written in the edition’s language: with the verso’s running head and the note on the text, they are what the Spanish edition changes.

#4 · Running heads in the language of each page

script.js · lines 117–128in full code
const head = (id, content, parity, edge, x, style) => ({ kind: 'text', id, content, parity,
  pages: 'opener', // every poem page opens with its title; a blank page stays bare
  fontFamily: LABEL, fontSize: pt(7.5), fontWeight: 600, color: col('muted'),
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(12) } }, ...style });
const header = { elements: [
  head('verso-folio', '{pageNumber}', 'even', 'top-left', EDGE, { color: col('ink') }),
  head('verso-book', '{subtitle}', 'even', 'top-left', EDGE + 8,
    { letterSpacing: pt(1.2), textTransform: 'uppercase' }),
  head('recto-poet', '{attr.name}', 'odd', 'top-right', -(EDGE + 8),
    { fontFamily: HEI, fontWeight: 400, fontSize: pt(8), letterSpacing: pt(3) }),
  head('recto-folio', '{pageNumber}', 'odd', 'top-right', -EDGE, { color: col('ink') }),
] };

Every page of this book opens with a heading, so every page is an opener, and the heads use pages: 'opener'. A blank page added by a break would stay bare, and the title page clears them with an empty header of its own. The verso takes the book’s title from the frontmatter’s subtitle, which each edition writes in its language; the recto takes the poet’s name from the name attribute of the Chinese heading (Headers & footers).

#5 · A title page on a moon

script.js · lines 88–113in full code
const onPage = (y, size) => ({ anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) },
  ...(size ? { size: { width: mm(size), height: mm(size) } } : {}) });
const [MOON_Y, MOON, HAN] = [36, 78, 60]; // mm: the moon's top and width; pt: the title
const UNDER = MOON_Y + MOON; // mm: the English lines start under the moon
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'), placement: onPage(y), ...style });
const titlePage = { id: 'title', span: 'page', runningChapter: false,
  header: { elements: [] }, footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'box', id: 'moon', placement: onPage(MOON_Y, MOON),
      style: { backgroundColor: col('moon'), borderRadius: mm(MOON / 2) } },
    line('han', '{titleText}', MOON_Y + MOON / 2 - (HAN * 25.4) / 144, { fontFamily: SERIF,
      fontWeight: 900, fontSize: pt(HAN), letterSpacing: pt(HAN / 4), lineHeight: 1 }),
    line('en', '{attr.en}', UNDER + 10, { fontFamily: LABEL, fontSize: pt(10), fontWeight: 600,
      letterSpacing: pt(3), textTransform: 'uppercase', color: col('seal') }),
    line('poets', '{attr.poets}', UNDER + 19, { fontFamily: ROMAN, fontSize: pt(12) }),
    line('giles', '{attr.english}', UNDER + 26, { fontFamily: ROMAN, fontSize: pt(11),
      italic: true }),
    // A seal reading 明月, the bright moon of three of the four poems, set down its square.
    { kind: 'box', id: 'seal', placement: onPage(170, 13),
      style: { backgroundColor: col('seal'), borderRadius: mm(1) } },
    line('seal-text', '明月', 170, { placement: onPage(170, 13), writingMode: 'vertical-rl',
      fontFamily: KAI, fontSize: pt(14), lineHeight: 1, color: col('paper'),
      verticalAlign: 'middle' }),
  ] } },
};

The title page is a heading style as well, with runningChapter: false so it names no chapter. The moon is a design box whose corner radius is half its side, and 唐詩 is centred on it by arithmetic: the moon’s middle, less half the title’s height. The seal sets 明月 with writingMode: 'vertical-rl', one character over the other, as seals are cut.

#6 · Each Chinese face loads what it sets

script.js · lines 306–316in full code
const grab = (re) => (markdown.match(re) ?? []).join('');
// Each poem to its closing `:::` (not the `:::space` between stanzas), then the note numbers.
const poems = grab(/:::paragraphs\{style="shi"\}[\s\S]*?\n:::(?=\n|$)/g) + '①②③④⑤⑥⑦⑧⑨⑩';
await loadFonts(FONTS, markdown);
await Promise.all([
  loadCjkFonts({ [SERIF]: ['400'] }, markdown + poems), // the notes and their ①, the heading blocks
  loadCjkFonts({ [SERIF]: ['700'] }, grab(/^# \S+(?= \{style="zh")|\*\*[^*]+\*\*/gm)),
  loadCjkFonts({ [SERIF]: ['900'] }, grab(/^# \S+(?= \{style="title")/gm)),
  loadCjkFonts({ [KAI]: ['400'] }, `${poems}明月`),
  loadCjkFonts({ [HEI]: ['400'] }, grab(/(?<=(?:poet|name)=")[^"]*/g)),
]);

Fontsource cuts each Chinese face into about a hundred files by character range, and loadCjkFonts fetches only the files its text needs (Chinese, Japanese and Korean fonts). The Kai gets the poems and the seal, the Hei the poet lines and names, the bold Song the four titles and the notes’ headwords, and its black weight the two characters of the title page.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 083 · Tang poems facing their English verse ═══════════════
// https://postext.dev/en/cookbook/tang-poems-facing-english
// Code: MIT · Text: Tang poems, zh.wikisource; H. A. Giles, 1901, Project Gutenberg (PD)
// Fonts: Noto Serif TC, LXGW WenKai TC, Noto Sans TC, Source Serif 4 (OFL) · Needs postext ≥ 1.28.0
import { buildDocument, withLoadedFonts, renderPageToCanvas } 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 = 'tang-poems-facing-english';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Ink and seal red on a cream paper, and a pale moon for the title page.
const palette = {
  ink: '#1f1b18', // text: a warm near-black
  seal: '#ad3526', // the accent: vermilion seal paste, for the poets, the rules and the seal
  moon: '#eadcb4', // the title page's moon
  leaf: '#f2e8cf', // the recto's tint, under the Chinese
  muted: '#6d655c', // running heads and the colophon
  paper: '#faf6ed', // a cream paper
};
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: 'seal (defaults)', value: { hex: palette.seal, model: 'hex' } },
];
const SERIF = 'Noto Serif TC'; // 明: the Chinese titles and the notes
const KAI = 'LXGW WenKai TC'; // 楷: the poems
const HEI = 'Noto Sans TC'; // 黑: the poet lines and the recto's running head
const ROMAN = 'Source Serif 4'; // the English: the Latin that Noto Serif TC is built on
const LABEL = 'Source Sans 3'; // English labels and folios
const [BODY, LEAD, SHI] = [10.5, 16, 16]; // pt: 五号 on a 16 pt pitch; the poems' size
const [CHARS, LINES] = [28, 30]; // the character grid: 28 ems by 30 lines
const TRIM = { width: 148, height: 210 }; // mm: 25開, a Taiwan trade trim
const [INNER, OUTER] = [18, 21]; // mm: minimum sides; the grid centres its measure between them
const MEASURE = (CHARS * BODY * 25.4) / 72; // 103.7 mm: 28 ems of 五号
const EDGE = OUTER + (TRIM.width - INNER - OUTER - MEASURE) / 2; // 23.6 mm: the outer text edge

// #region answer: the English opens the next verso, the Chinese the recto that faces it
const SINK = 6; // lines of LEAD under both titles, so the two poems start on the same line
const at = (y) => ({ anchor: { to: 'container', edge: 'top' }, offset: { y: mm(y) } });
// A title whose foot is 23 mm down at any size, and the poet's line under it at 24 mm.
const titled = (size, title, poet, under = []) => ({
  enabled: true, minHeight: pt(SINK * LEAD),
  slot: { elements: [...under,
    { kind: 'text', id: 'title', content: '{titleText}', fontSize: pt(size), lineHeight: 1.2,
      align: 'center', overflow: 'wrap', color: col('ink'),
      placement: at(23 - (size * 1.2 * 25.4) / 72), ...title },
    { kind: 'text', id: 'poet', align: 'center', overflow: 'wrap', color: col('seal'),

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

#Put the original on the verso

Loeb editions and many Chinese–English readers set the original on the left: swap the parities of the two heading styles and of the two running heads that name the book and the poet, and write each Chinese heading and poem before its English in the Markdown.

-const english = { id: 'en', breakBefore: { enabled: true, parity: 'even' }, // a verso
+const english = { id: 'en', breakBefore: { enabled: true, parity: 'odd' }, // a recto
-const chinese = { id: 'zh', span: 'page', breakBefore: { enabled: true, parity: 'odd' },
+const chinese = { id: 'zh', span: 'page', breakBefore: { enabled: true, parity: 'even' },
-  head('verso-book', '{subtitle}', 'even', 'top-left', EDGE + 8,
+  head('verso-book', '{subtitle}', 'odd', 'top-right', -(EDGE + 8),
-  head('recto-poet', '{attr.name}', 'odd', 'top-right', -(EDGE + 8),
+  head('recto-poet', '{attr.name}', 'even', 'top-left', EDGE + 8,

#Set the glosses right under the poem

Chinese annotated anthologies (注釋本) print the notes after each poem. Chapter-end notes do it here, since each poem is a chapter of its own.

-const footnotes = { placement: 'column', numbering: 'page', // the page foot; ① again on each page
+const footnotes = { placement: 'chapterEnd', chapterEndAlign: 'text',

Pitfalls

Pitfall

A heading style inherits its level's page break

A headingStyles entry takes every field it leaves out from its heading level, breakBefore included. A contents page or a colophon styled on an H1 after a :::pagebreak inherits parity 'odd' and lands behind a blank page. Give such a style breakBefore: { enabled: false }. Heading styles →

Pitfall

Page 1 is a recto: plan pages with physical numbers

Page 1 is a right-hand page and page 2 the first verso, so plan spreads with physical page numbers: an opener on an even page faces the odd page after it. Page and column breaks →

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

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 →

Pitfall

A Chinese face sets quotation marks and apostrophes full width, in Latin text too

Noto Serif TC and the other Traditional Chinese faces draw ‘ ’ “ ” one em wide, the way Chinese text uses them, and that glyph is what a Latin word set in the face gets: Li Bai’s prints with a wide gap after the apostrophe, and an English quotation opens and closes on a full em of blank. A CJK face has no italic either, and the slant faked on screen prints upright in the PDF. Text that mixes Chinese with a Latin language in one face (footnotes, which take the body face, or glosses with pinyin) reads best without apostrophes, curly quotes and italics; « » and the Latin-1 marks keep their width. Where the Latin text runs on its own, give it a Latin face through a paragraph style. Chinese, Japanese and Korean fonts →

Credits

Text
  • Three Tang poems in traditional characters, Li Bai’s 靜夜思 and 月下獨酌 and Wang Wei’s 竹里館, as Three Hundred Tang Poems (1763) gives them · Li Bai, Wang Wei · public domain
  • Du Fu’s 絕句, the second of his 絕句二首, as the Complete Tang Poems (1705, juan 228) prints it · Du Fu · public domain
  • The English verse translations, from A History of Chinese Literature (1901), Project Gutenberg eBook 43711 · Herbert A. Giles · public domain
  • The notes, the English titles, the note on the text and the colophon · Postext Cookbook · original
Fonts
Noto Serif TC (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · Source Serif 4 (SIL OFL 1.1) · Source Sans 3 (SIL OFL 1.1)
SandboxPDF