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
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
- Features
- Chapters that open on a rectoHeading stylesFootnotesParagraph stylesCharacter gridChinese, Japanese and Korean fontsChinese line breakingDesigned openersHeading attributesText, rules and boxes in page designsCovers, title pages and colophonsRunning heads and foliosRunning heads per sectionHeads by page roleMirrored marginsPaper colourSemantic colour paletteExplicit vertical spacePDF exportFonts embedded in the PDF
- 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).
#2 · A row of Chinese for two lines of English
// Each indent centres the longest line of the poems that use it on the 103.7 mm measure:
// 97.8 mm in the moonlight poem, 91–93 mm in two quatrains, 66 mm in Wang Wei's.
const verses = [['verse-long', 3], ['verse', 6], ['verse-short', 19]].map(([id, indent]) => ({
id, fontFamily: ROMAN, fontSize: pt(BODY), lineHeight: pt(LEAD), textAlign: 'left',
firstLineIndent: pt(0), indent: mm(indent) }));
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) };
// A paragraph drops its leading spaces (gap: hard-line-breaks): the two spaces Giles indents
// his rhyming lines by become two em spaces behind a word joiner, which nothing trims.
const indentVerse = (md) => md.replace(/^ {2}(?=\S)/gm, '\u2060\u2003\u2003');
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 the same :::space{lines=1} goes into both texts, 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 number stands after its row’s 。, outside the twelve: inside the row it would push every character after it a third of an em to the right, out of line with the row below. The English indents come from measuring each poem’s longest line. Giles indents every other line; the Markdown keeps his two spaces, and indentVerse turns them into em spaces behind a word joiner, because a paragraph drops the spaces it starts with.
#3 · Glosses at the foot of the Chinese page
const footnotes = { placement: 'column', // the foot of the column, here the foot of the page
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') } };
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. Numbering starts again at every heading that opens a page, so each poem counts its notes from 1 (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
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
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
const grab = (re) => (markdown.match(re) ?? []).join('');
const poems = grab(/:::paragraphs\{style="shi"\}[\s\S]*?\n:::/g) + '0123456789'; // and note numbers
await loadFonts(FONTS, markdown);
await Promise.all([
loadCjkFonts({ [SERIF]: ['400'] }, markdown), // the notes, and 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
// ═══ 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.9.0 import { buildDocument, renderPageToCanvas, clearMeasurementCache } 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'), 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' } } }]) }; // #endregion // #region verse: a Chinese row faces two lines of English on the grid both pages share // Each indent centres the longest line of the poems that use it on the 103.7 mm measure: // 97.8 mm in the moonlight poem, 91–93 mm in two quatrains, 66 mm in Wang Wei's. const verses = [['verse-long', 3], ['verse', 6], ['verse-short', 19]].map(([id, indent]) => ({ id, fontFamily: ROMAN, fontSize: pt(BODY), lineHeight: pt(LEAD), textAlign: 'left', firstLineIndent: pt(0), indent: mm(indent) })); 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) }; // A paragraph drops its leading spaces (gap: hard-line-breaks): the two spaces Giles indents // his rhyming lines by become two em spaces behind a word joiner, which nothing trims. const indentVerse = (md) => md.replace(/^ {2}(?=\S)/gm, '\u2060\u2003\u2003'); // #endregion // #region notes: glosses at the foot of the recto, in the edition's language const footnotes = { placement: 'column', // the foot of the column, here the foot of the page 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') } }; // #endregion // #region title: 唐詩 on a pale moon, with a seal 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' }), ] } }, }; // #endregion // #region heads: the book in English over the verso, the poet in Chinese over the recto 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') }), ] }; // #endregion const paragraphStyles = [shi, ...verses, // Justified like the body, and divided by the patterns of the edition's language (bodyText). { id: 'prose', fontFamily: ROMAN, fontSize: pt(10), lineHeight: pt(LEAD), firstLineIndent: mm(4) }, { id: 'colophon', fontFamily: LABEL, fontSize: pt(7), lineHeight: pt(10), color: col('muted'), italicColor: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(LEAD) }, ]; const config = () => ({ // a factory: the engine caches resolved configs per object locale: 'zh-Hant', // the Chinese sets the rules; written out, never LANG (gotcha: cjk-locale-tag) colorPalette, page: { width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150, backgroundColor: col('paper'), // 23 + 17.5 mm leave 169.5 mm for 30 lines of 16 pt (169.3 mm): a head deeper than the foot. margins: { top: mm(23), bottom: mm(17.5), left: mm(INNER), right: mm(OUTER), mirror: true }, }, layout: { layoutType: 'single' }, cjk: { grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES } }, bodyText: { fontFamily: SERIF, fontSize: pt(BODY), lineHeight: pt(LEAD), color: col('ink'), boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'), textAlign: 'justify', firstLineIndent: em(2), indentAfterHeading: false, hyphenation: { enabled: true, locale: LANG } }, // no Chinese patterns: the Latin's language // The designs paint the titles; weight 400 keeps the heading blocks in a loaded face. // Restated: any headings object drops the H1 break (gotcha: headings-drop-h1-break). headings: { fontFamily: SERIF, fontWeight: 400, levels: [{ level: 1, marginTop: pt(0), marginBottom: pt(0), breakBefore: { enabled: true, parity: 'any' } }] }, headingStyles: [titlePage, english, chinese], paragraphStyles, footnotes, header, footer: { elements: [] }, }); // ─── 2 · Content ──────────────────────────────────────────────────────────── const markdown = String.raw`---Markdown sample · 153 lines · content.en.md
title: "唐詩" subtitle: "Tang Poems" --- # 唐詩 {style="title" en="Tang Poems" poets="Li Bai · Du Fu · Wang Wei" english="with the English verse of Herbert A. Giles"} # Night Thoughts {style="en" kicker="Li Bai · 701–762"} :::paragraphs{style="verse"} I wake, and moonbeams play around my bed, Glittering like hoar-frost to my wondering eyes; Up towards the glorious moon I raise my head, Then lay me down,—and thoughts of home arise. ::: # 靜夜思 {style="zh" poet="〔唐〕李白" name="李白"} :::paragraphs{style="shi"} 牀前明月光，疑是地上霜。[^bed] 舉頭望明月，低頭思故鄉。[^moon] ::: [^bed]: **牀** chuáng, now written 床: a bed. Some commentators read it as the railing round a well, others as a folding seat set out in the courtyard; Giles keeps the bed. [^moon]: **明月** míngyuè, the bright moon. The collected works of Li Bai read 山月 here, the moon over the hills, and 看月光 in the first line; the 1705 edition of all Tang poetry reads 山月 but keeps 明月光. This page follows the anthology of 1763, the text Chinese children learn by heart. **鄉** xiāng rhymes with 光 guāng and 霜 shuāng at the ends of the first two lines; Giles rhymes his quatrain on alternate lines instead. # Drinking Alone under the Moon {style="en" kicker="Li Bai · 701–762"} :::paragraphs{style="verse-long"} An arbour of flowers and a kettle of wine: Alas! in the bowers no companion is mine. Then the moon sheds her rays on my goblet and me, And my shadow betrays we’re a party of three. :::space{lines=1} Though the moon cannot swallow her share of the grog, And my shadow must follow wherever I jog,— Yet their friendship I’ll borrow and gaily carouse, And laugh away sorrow while spring-time allows. :::space{lines=1} See the moon,—how she glances response to my song; See my shadow,—it dances so lightly along! While sober I feel you are both my good friends; When drunken I reel, our companionship ends. But we’ll soon have a greeting without a good-bye, At our next merry meeting away in the sky. ::: # 月下獨酌 {style="zh" poet="〔唐〕李白" name="李白"} :::paragraphs{style="shi"} 花間一壺酒，獨酌無相親。 舉杯邀明月，對影成三人。[^three] :::space{lines=1} 月既不解飲，影徒隨我身。 暫伴月將影，行樂須及春。[^jiang] :::space{lines=1} 我歌月徘徊，我舞影零亂。 醒時同交歡，醉後各分散。 永結無情遊，相期邈雲漢。[^wuqing] ::: [^three]: **三人** sān rén, three people: the poet, the moon and his shadow. [^jiang]: **將** jiāng: here it joins 月 to 影, the moon to the shadow. [^wuqing]: **無情遊** wúqíng yóu: a friendship with companions who feel nothing, the moon and the shadow; the poet binds himself to it for good. **雲漢** yúnhàn: the Milky Way, where the three will meet again, away in the sky. The rhyme changes at the ninth line, where the third stanza of Giles begins. # Stop-short {style="en" kicker="Du Fu · 712–770"} :::paragraphs{style="verse"} White gleam the gulls across the darkling tide, On the green hills the red flowers seem to burn; Alas! I see another spring has died…. When will it come—the day of my return? ::: # 絕句 {style="zh" poet="〔唐〕杜甫" name="杜甫"} :::paragraphs{style="shi"} 江碧鳥逾白，山青花欲燃。[^yu] 今春看又過，何日是歸年。[^guinian] ::: [^yu]: **逾** yú, all the more: against the green of the river the birds look whiter still. **欲燃** yù rán, about to catch fire: the red of the flowers, which in Giles seem to burn. [^guinian]: **歸年** guī nián, the year of going home. Du Fu wrote this quatrain, the second of a pair, in the spring of 764 at Chengdu, where the war in the north had driven him. # The Bamboo Lodge {style="en" kicker="Wang Wei · 701–761"} :::paragraphs{style="verse-short"} Beneath the bamboo grove, alone, I seize my lute and sit and croon; No ear to hear me, save mine own: No eye to see me—save the moon. ::: # 竹里館 {style="zh" poet="〔唐〕王維" name="王維"} :::paragraphs{style="shi"} 獨坐幽篁裏，彈琴復長嘯。[^huang] 深林人不知，明月來相照。 ::: [^huang]: **幽篁** yōuhuáng: a deep, dark grove of bamboo. **長嘯** cháng xiào: a long whistle through pursed lips, the art of recluses; in Giles the poet croons. The Bamboo Lodge was one of twenty places on the estate of Wang Wei at Wangchuan, south-east of the Tang capital, and he gave each of them a quatrain in 輞川集, the Wangchuan collection. # A note on the text {style="en" kicker="About this edition"} :::paragraphs{style="prose"} The Chinese poems follow *Three Hundred Tang Poems*, the anthology Sun Zhu compiled in 1763 under the name Hengtang Tuishi, except Du Fu’s quatrain, which is not in it and is printed as the *Complete Tang Poems* of 1705 gives it. All four are taken from Wikisource in traditional characters, with the old forms of some characters as found there. The English verse is Herbert A. Giles’s, as he printed it in *A History of Chinese Literature* (1901), where the poems have no titles; the English titles are this edition’s. Giles wrote Li Po and Tu Fu for Li Bai and Du Fu, and called the four-line *jueju* a “stop-short”, which gives Du Fu’s poem its English name. His rhymes, indents and punctuation are kept; the moonlight poem, which his book printed in half-lines, is set here in whole lines. Each Chinese poem is set two lines of verse to a row, so that every row faces the two lines of English that render it. The space between the stanzas of the moonlight poem is the editor’s, added on both pages. ::: :::paragraphs{style="colophon"} Set in Noto Serif TC, LXGW WenKai TC and Noto Sans TC for the Chinese, Source Serif 4 and Source Sans 3 for the English, all under the SIL Open Font License · Chinese text: Wikisource · English verse: H. A. Giles, *A History of Chinese Literature*, 1901, Project Gutenberg eBook 43711 :::`; // content.<lang>.md, inlined by the Cookbook // ─── 3 · Fonts ────────────────────────────────────────────────────────────── const FONTS = { // every face the pages use, loaded before the build (gotcha: fonts-first) 'Noto Serif TC': ['400', '700', '900'], // SERIF: the notes; the titles; 唐詩 'LXGW WenKai TC': ['400'], // KAI: the poems and the seal 'Noto Sans TC': ['400'], // HEI: the poet lines, the recto's head 'Source Serif 4': ['400', '400i'], // ROMAN: the verse, the titles, the note on the text 'Source Sans 3': ['400', '400i', '600'], // LABEL: kickers, the verso's head, folios, colophon }; // ─── 4 · Build & show ─────────────────────────────────────────────────────── // #region voices: each Chinese face loads the files of the characters it sets const grab = (re) => (markdown.match(re) ?? []).join(''); const poems = grab(/:::paragraphs\{style="shi"\}[\s\S]*?\n:::/g) + '0123456789'; // and note numbers await loadFonts(FONTS, markdown); await Promise.all([ loadCjkFonts({ [SERIF]: ['400'] }, markdown), // the notes, and 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)), ]); // #endregion const doc = await buildWithFonts( () => buildDocument({ markdown: indentVerse(markdown) }, config()), markdown); showPages(doc, { title: t({ en: 'Tang poems facing their English verse', es: 'Poemas Tang frente a su versión inglesa' }) }); offerPdf(() => renderToPdf(doc, { fontProvider: cjkPdfProvider }), `${RECIPE}.pdf`);Kit · core, fonts, viewer, pdf, cjk: the same in every recipe · 422 lines
// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ───── // ─── Kit · core v1 ── the same in every recipe · postext.dev/cookbook ───────── function mm(value) { return { value, unit: 'mm' }; } function pt(value) { return { value, unit: 'pt' }; } function em(value) { return { value, unit: 'em' }; } /** The sample language's string: t({ en: 'Figure', es: 'Figura' }). */ function t(strings) { return strings[LANG] ?? Object.values(strings)[0]; } /** A file in this recipe's assets folder, served from the Postext repo by jsDelivr. */ function asset(file) { return `https://cdn.jsdelivr.net/gh/drnachio/postext@main/cookbook/${RECIPE}/assets/${file}`; } // ─── Kit · fonts v1 ── the same in every recipe · postext.dev/cookbook ──────── // Postext measures text with the faces the browser has loaded, and caches the // widths, so every face must be ready before the first build. Faces come from // Fontsource: the same static files the PDF embeds, so screen and PDF agree. /** faces = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample: * letters beyond Latin-1 (č, ł, ő…) also load the latin-ext files. With * `optional`, a face Fontsource does not ship is skipped instead of failing. * Resolves to the number of faces added. */ async function loadFonts(faces, text = '', { optional = false } = {}) { kitStatus('Loading fonts…'); const ranges = { latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,' + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD', 'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,' + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF', }; const subsets = /[Ā-˿Ḁ-ỿ]/.test(text) ? ['latin', 'latin-ext'] : ['latin']; const jobs = []; let added = 0; for (const [family, specs] of Object.entries(faces)) { const id = fontsourceId(family); const meta = optional ? await fontsourceMeta(family) : null; for (const spec of new Set(specs)) { const weight = parseInt(spec, 10); const style = spec.endsWith('i') ? 'italic' : 'normal'; if (hasFace(family, weight, style)) continue; if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue; for (const subset of subsets) { const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`; const face = new FontFace(family, `url(${url}) format('woff2')`, { weight: String(weight), style, unicodeRange: ranges[subset] }); jobs.push(face.load().then((ready) => { document.fonts.add(ready); added++; }, () => { if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`); })); } } } await Promise.all(jobs).catch((error) => { kitFail(error); throw error; }); return added; } /** Runs `build` (a buildDocument or buildBundle call) and checks the faces * the pages use. A regular face missing from FONTS is loaded with a warning; * bold and italic variants are loaded when the family ships them. Then the * measurement caches are cleared and the build runs again. */ async function buildWithFonts(build, text = '') { const tried = new Set(); for (let round = 0; round < 3; round++) { kitStatus('Laying out…'); await new Promise(requestAnimationFrame); // let the status paint first const result = await Promise.resolve().then(build).catch((error) => { kitFail(error); throw error; }); const wanted = { base: {}, variants: {} }; for (const { font, base } of [result].flat().flatMap(fontStringsOf)) { const { family, weight, style } = parseFont(font); const key = `${family}|${weight}|${style}`; if (tried.has(key) || hasFace(family, weight, style)) continue; tried.add(key); (wanted[base ? 'base' : 'variants'][family] ??= []).push(`${weight}${style === 'italic' ? 'i' : ''}`); } if (Object.keys(wanted.base).length) { console.warn(`[cookbook] FONTS does not list ${JSON.stringify(wanted.base)}: loading them.`); } const added = await loadFonts(wanted.base, text) + await loadFonts(wanted.variants, text, { optional: true }); if (added === 0) return result; clearMeasurementCache(); } throw new Error('The fonts did not settle after three builds.'); } /** Every font string of the layout. `base` marks a block's own face; its * bold, italic and bold-italic variants are listed whether or not used. */ function fontStringsOf(doc) { const found = new Map(); const walk = (node) => { if (!node || typeof node !== 'object') return; if (Array.isArray(node)) { node.forEach(walk); return; } for (const [key, value] of Object.entries(node)) { if (typeof value === 'string' && /fontString$/i.test(key)) { found.set(value, found.get(value) || key === 'fontString'); } else if (value && typeof value === 'object') walk(value); } }; walk(doc.pages); walk(doc.blocks); return [...found].map(([font, base]) => ({ font, base })); } /** '700 37.5px Open Sans' / 'italic 400 13px "Source Serif 4"' → { family, weight, style }. * A string with no weight ('95.8px Young Serif', from a design text) is 400. */ function parseFont(font) { const m = /^(?:(italic|oblique)\s+)?(?:small-caps\s+)?(?:(\d+|bold|normal)\s+)?[\d.]+px\s+(.+)$/.exec(font.trim()); if (!m) throw new Error(`Unexpected font string: ${font}`); const weight = m[2] === 'bold' ? 700 : !m[2] || m[2] === 'normal' ? 400 : Number(m[2]); return { family: m[3].replace(/^["']|["']$/g, ''), weight, style: m[1] ? 'italic' : 'normal' }; } /** True when a loaded FontFace covers exactly this family, weight and style * (document.fonts.check() is also true for families nobody declared). */ function hasFace(family, weight, style) { for (const face of document.fonts) { if (face.status !== 'loaded' || face.style !== style) continue; if (face.family.replace(/^["']|["']$/g, '') !== family) continue; const [low, high = low] = face.weight.split(' ').map(Number); if (weight >= low && weight <= high) return true; } return false; } /** Fontsource's id for a family: 'Source Serif 4' → 'source-serif-4'. */ function fontsourceId(family) { return family.toLowerCase().replace(/\s+/g, '-'); } /** The weights and styles a family ships ({ weights: [400, 700], styles: ['normal', 'italic'] }), or null. */ function fontsourceMeta(family) { fontsourceMeta.cache ??= new Map(); const id = fontsourceId(family); if (!fontsourceMeta.cache.has(id)) { fontsourceMeta.cache.set(id, fetch(`https://api.fontsource.org/v1/fonts/${id}`) .then((res) => (res.ok ? res.json() : null), () => null)); } return fontsourceMeta.cache.get(id); } // ─── Kit · viewer v1 ── the same in every recipe · postext.dev/cookbook ─────── /** Shows the pages as facing spreads on a dark desk: the first page is a * recto on its own, then verso | recto pairs, as in a bound book. Pages * are painted when they scroll near the screen. */ function showPages(docs, { title, width = 460 } = {}) { const root = viewer(title); const pages = [docs].flat().flatMap((doc) => doc.pages.map((page) => ({ doc, page, n: (doc.pageIndexOffset ?? 0) + page.index }))); const spreads = []; let verso = null; for (const p of pages) { if (p.n % 2 === 1) { if (verso) spreads.push([verso, null]); verso = p; } else { spreads.push([verso, p]); verso = null; } } if (verso) spreads.push([verso, null]); const density = Math.min(window.devicePixelRatio || 1, 2); showPages.painter?.disconnect(); const painter = new IntersectionObserver((entries) => { for (const { isIntersecting, target } of entries) { if (!isIntersecting) continue; painter.unobserve(target); const { doc, page } = target.postext; renderPageToCanvas(page, doc, target, { scale: (width * density) / page.width }); } }, { rootMargin: '800px' }); showPages.painter = painter; root.replaceChildren(...spreads.map((pair) => { const spread = document.createElement('div'); spread.className = 'pt-spread'; for (const p of pair) { const figure = document.createElement('figure'); if (p) { const label = p.page.pageLabel || String(p.n + 1); const canvas = document.createElement('canvas'); canvas.postext = p; canvas.style.aspectRatio = `${p.page.width} / ${p.page.height}`; canvas.setAttribute('role', 'img'); canvas.setAttribute('aria-label', `Page ${label}`); const folio = document.createElement('figcaption'); folio.textContent = label; figure.append(canvas, folio); painter.observe(canvas); } else figure.className = 'pt-blank'; spread.append(figure); } return spread; })); kitStatus(`${pages.length} ${pages.length === 1 ? 'page' : 'pages'}`); document.documentElement.dataset.postext = 'ready'; return pages.length; } /** The desk, the bar and the error reporting, created once. */ function viewer(title) { if (!document.getElementById('pt-kit')) { document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit"> :root { color-scheme: dark; } body { margin: 0; background: #0e1014; color: #b9bcc4; font: 13px/1.45 system-ui, sans-serif; } #pt-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center; gap: 6px 16px; padding: 10px 16px; background: rgb(14 16 20 / .92); backdrop-filter: blur(6px); border-bottom: 1px solid #23262d; } #pt-bar strong { color: #f4f1ea; font-weight: 600; } #pt-actions { display: flex; gap: 12px; margin-left: auto; } #pt-actions a, #pt-actions button { color: #d8a21a; font: inherit; background: none; border: 0; padding: 0; cursor: pointer; } #pages { display: grid; justify-items: center; gap: 48px; padding: 32px 16px 72px; } .pt-spread { display: flex; } .pt-spread figure { margin: 0; width: min(460px, 44vw); } .pt-spread canvas { display: block; width: 100%; background: #fff; box-shadow: 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); } .pt-spread figure:first-child canvas { box-shadow: inset -14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); } .pt-spread figcaption { margin-top: 10px; text-align: center; font: 600 10px/1 system-ui, sans-serif; letter-spacing: .18em; text-transform: uppercase; color: #6c7079; } .pt-blank { visibility: hidden; } @media (max-width: 760px) { .pt-spread { flex-direction: column; gap: 32px; } .pt-spread figure { width: min(460px, 92vw); } .pt-blank { display: none; } } </style>`); document.body.insertAdjacentHTML('afterbegin', '<header id="pt-bar"><strong id="pt-title"></strong><span id="pt-status" role="status"></span><span id="pt-actions"></span></header>'); document.getElementById('pt-title').textContent = document.title || 'Postext'; addEventListener('error', (event) => kitFail(event.error ?? event.message)); addEventListener('unhandledrejection', (event) => kitFail(event.reason)); } if (title) document.getElementById('pt-title').textContent = title; return document.getElementById('pages') ?? document.body.appendChild(Object.assign(document.createElement('main'), { id: 'pages' })); } function kitStatus(text) { viewer(); document.getElementById('pt-status').textContent = text; } function kitFail(error) { document.documentElement.dataset.postext = 'error'; kitStatus(`Error: ${error?.message ?? error}`); } // ─── Kit · pdf v1 ── the same in every recipe that exports a PDF ────────────── /** postext-pdf embeds TrueType bytes. Fetch the Fontsource file the screen * used, snapping to a weight the family ships and falling back to upright * when it has no italic: the PDF asks for every face a block could use. */ async function fontsourceProvider(family, weight, style) { const id = fontsourceId(family); const meta = await fontsourceMeta(family); const weights = meta?.weights?.length ? meta.weights : [400, 700]; const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a)); const s = style === 'italic' && meta && !meta.styles.includes('italic') ? 'normal' : style; const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`); if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} (${res.status})`); return decompressWoff2(new Uint8Array(await res.arrayBuffer())); } /** A "Build the PDF" button in the bar. Once built: "Open the PDF" (a new * tab, since CodePen's preview frame cannot show PDFs) and a download link. */ function offerPdf(makePdf, filename) { viewer(); const button = Object.assign(document.createElement('button'), { type: 'button', textContent: 'Build the PDF' }); button.dataset.postextPdf = filename; button.addEventListener('click', async () => { button.disabled = true; button.textContent = 'Building the PDF…'; try { const bytes = await makePdf(); const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' })); const size = `${Math.max(1, Math.round(bytes.length / 1024))} KB`; button.replaceWith( Object.assign(document.createElement('a'), { href: url, target: '_blank', rel: 'noopener', textContent: 'Open the PDF ↗' }), Object.assign(document.createElement('a'), { href: url, download: filename, textContent: `Download ${filename} · ${size}` })); } catch (error) { button.disabled = false; button.textContent = 'Build the PDF'; kitFail(error); } }); document.getElementById('pt-actions').append(button); } // ─── Kit · cjk v1 ── Chinese, Japanese and Korean books · postext.dev/cookbook ─ // Fontsource ships a CJK family as about a hundred files per weight, each // declared in its stylesheet with the unicode-range it covers. The screen // loads the files the sample touches; the PDF gets the same files for the // characters its pages set in each face, and embeds each as a subset. // A book bound on the right (vertical text) is shown with its spreads // mirrored: page 1 alone on the left of the spine, then [3 | 2]. /** The files of a Fontsource face, read from its stylesheet: { url, range, * ranges }, the last declared first (the order the browser tries them in). */ function cjkSlices(family, weight, style) { cjkSlices.cache ??= new Map(); const id = fontsourceId(family); const css = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/${weight}${style === 'italic' ? '-italic' : ''}.css`; if (!cjkSlices.cache.has(css)) { cjkSlices.cache.set(css, fetch(css) .then((res) => { if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style} (${res.status})`); return res.text(); }) .then((text) => [...text.matchAll(/@font-face\s*{([^}]*)}/g)].map(([, rule]) => { const range = /unicode-range:\s*([^;]+);/.exec(rule)?.[1].trim() ?? 'U+0-10FFFF'; const ranges = range.split(',').map((part) => { const [lo, hi = lo] = part.trim().slice(2).split('-'); return [parseInt(lo, 16), parseInt(hi, 16)]; }); return { url: new URL(/url\(([^)]+?\.woff2)\)/.exec(rule)[1], css).href, range, ranges }; }).reverse())); } return cjkSlices.cache.get(css); } /** The file of `slices` that holds code point `cp`, if any. */ function cjkSliceFor(slices, cp) { return slices.find((slice) => slice.ranges.some(([lo, hi]) => cp >= lo && cp <= hi)); } /** Whether Fontsource serves `family` as a Chinese, Japanese or Korean * family (its subsets name the script). Fails when the API does not * answer: a CJK face taken for a Latin one would paint in a system face. */ async function isCjkFamily(family) { const meta = await fontsourceMeta(family); if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`); return !!meta.subsets?.some((subset) => /^(chinese|japanese|korean)/.test(subset)); } /** faces = { 'Noto Serif TC': ['400', '700'] }, as for loadFonts: the * whole FONTS object may be passed, its other families are left to * loadFonts. Adds one FontFace per file of each CJK face with its * unicodeRange, then loads the files `text` touches. `text` is what the * faces set: the sample for the text face; a book in several voices calls * it once per voice (loadCjkFonts({ 'LXGW WenKai TC': ['400'] }, quotes)), * so the heading and quotation faces fetch and check only their own * characters. Fails when a character of `text` is in no file of a face. * List every weight the pages use: a weight left to buildWithFonts gets * the latin file only. With { vertical: true } it also loads each * family's vertical forms (brackets, quotes, pause marks) for the canvas, * which needs loadVerticalAlternates imported from postext. Resolves to * the number of files loaded. */ async function loadCjkFonts(faces, text, { vertical = false } = {}) { kitStatus('Loading fonts…'); let loaded = 0; try { if (vertical && typeof loadVerticalAlternates !== 'function') { throw new Error('loadCjkFonts(…, { vertical: true }) needs loadVerticalAlternates imported from postext'); } for (const [family, specs] of Object.entries(faces)) { if (!(await isCjkFamily(family))) continue; const twin = []; for (const spec of new Set(specs)) { const weight = parseInt(spec, 10); const style = spec.endsWith('i') ? 'italic' : 'normal'; const slices = await cjkSlices(family, weight, style); const missing = [...new Set(text)].filter((ch) => /\S/.test(ch) && !cjkSliceFor(slices, ch.codePointAt(0))); if (missing.length) { throw new Error(`${family} ${spec} has no file for ${missing.slice(0, 12).join(' ')}: ` + `give each face the text it sets (loadCjkFonts({ '${family}': ['${spec}'] }, text))`); } for (const slice of slices) { document.fonts.add(new FontFace(family, `url(${slice.url}) format('woff2')`, { weight: String(weight), style, unicodeRange: slice.range })); twin.push({ source: slice.url, weight: String(weight), style, unicodeRange: slice.range }); } const font = `${style === 'italic' ? 'italic ' : ''}${weight} 16px "${family}"`; loaded += (await document.fonts.load(font, text)).length; if (!document.fonts.check(font, text)) throw new Error(`${family} ${spec} did not load for the sample`); } // The same files under a twin name with the `vert` feature on: the // canvas paints the punctuation of vertical lines with it. if (vertical && twin.length) await loadVerticalAlternates(family, twin); } } catch (error) { kitFail(error); throw error; } return loaded; } /** The PDF font provider for recipes with CJK faces: a family whose * Fontsource subsets are Chinese, Japanese or Korean gets the files that * hold the characters its pages set (`request.codePoints`); any other * family goes to fontsourceProvider (the "pdf" block). */ async function cjkPdfProvider(family, weight, style, request) { if (!(await isCjkFamily(family))) return fontsourceProvider(family, weight, style); const meta = await fontsourceMeta(family); const weights = meta.weights?.length ? meta.weights : [400, 700]; const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a)); const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style; const slices = await cjkSlices(family, w, s); const picked = new Set(); for (const cp of request?.codePoints ?? []) { const slice = cjkSliceFor(slices, cp); if (slice) picked.add(slice); } if (!picked.size) picked.add(slices[0]); return Promise.all(slices.filter((slice) => picked.has(slice)).map(async (slice) => { const res = await fetch(slice.url); if (!res.ok) throw new Error(`Fontsource file ${slice.url} (${res.status})`); return decompressWoff2(new Uint8Array(await res.arrayBuffer())); })); } /** showPages for a book bound on either edge. A right-bound book (the * document says so: doc.binding is 'right' for page.binding 'right' and * for vertical text) lies on the desk as it opens: page 1 alone on the * left of the spine, then [3 | 2], the spine shade on each page's inner * edge. `binding` ('left' | 'right') overrides the document's. */ function showBook(docs, { binding, ...options } = {}) { const count = showPages(docs, options); const right = (binding ?? [docs].flat()[0]?.binding) === 'right'; if (!document.getElementById('pt-kit-cjk')) { // The pages keep direction ltr: a canvas draws text in the direction its // element inherits, and under rtl each run would end where the engine // starts it, its brackets mirrored. document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit-cjk"> .pt-spread[dir="rtl"] canvas { direction: ltr; } .pt-spread[dir="rtl"] figure:first-child canvas { box-shadow: inset 14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); } </style>`); } // Each pair stays [verso, recto] in the page; right to left, the verso // sits on the right. Phones stack the pages in reading order either way. for (const spread of document.querySelectorAll('#pages > .pt-spread')) spread.dir = right ? 'rtl' : 'ltr'; document.getElementById('pages').dataset.binding = right ? 'right' : 'left'; return count; } // ─── /Kit ───────────────────────────────────────────────────────────────────────
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 ↗
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', // the foot of the column, here the foot of the 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. 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. 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 →
Pitfall
Any headings object switches off the H1 page break
By default an H1 breaks to a recto (always-odd), but passing any headings object resets that default, so chapters run on and span: 'page' does nothing. Restate headings.levels[0].breakBefore: { enabled: true, parity } in every config. Chapters that open on a recto →
Pitfall
Load every face before layout
Layout measures text with the faces the browser has loaded and caches the widths, so a face that arrives after the first build leaves wrong line breaks and a PDF that no longer matches the screen. Load every weight and style first, and call clearMeasurementCache() before rebuilding when one arrives late. Fonts before layout →
Credits
- Recipe
- Ignacio Ferro
- 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)
