Skip to main content
Recipe number 86

Cookbook · Chapter 4 · Running heads & folios

A Chinese dictionary page with guide words

Four pages of a Kangxi Dictionary reader in pinyin order: {firstMark.h2} and {lastMark.h2} print each page’s first and last headword in its running head.

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

pp. 634–635 · 1–2 of 4

  • Trim 140 × 203 mm
  • 2 columns, 6.3 mm gutter
  • Noto Serif TC 9/15
  • LXGW WenKai TC
  • Noto Sans TC
  • 4 pages
  • Level
  • Postext 1.65.0
  • Laid out in 88 ms
  • 158 lines of code

In short

Four pages of a classic Chinese dictionary. The top corner of each page shows its first and last entry, so readers can find a word by flipping through.

What you'll build

Four pages from the middle of a reader’s edition of the Kangxi Dictionary (康熙字典, 1716), rearranged in pinyin order from 天 tiān to 庭 tíng. Each headword stands in red Song Black with its pinyin over it; the rhyme-book readings (反切) and the senses follow in one paragraph, the senses numbered ① ② in the same red. The page is 大32开, 140 × 203 mm, two columns of 17 characters of 小五 (9 pt) on a grid of 31 lines, each column full to its last line. At the outer corner of every page the running head names the first and the last headword on it, so a reader looking for 蜩 turns to the page headed 腆—髫. The Sailor’s Word-Book is the Latin-script dictionary to compare it with.

This recipe answers

  • How do I print the first and last headword of each page in a dictionary's running head?
  • How do I add pinyin above Chinese characters?
  • How do I get Chinese characters into the PDF without empty boxes?

The short answer

script.js · lines 37–58in full code
// Each headword is a level-2 heading, '## {天|tiān}'. {firstMark.h2} prints the text of the
// first one that starts on the page, without its reading, and {lastMark.h2} the last; a
// page on which none starts repeats the one in force. They stand at the outer corner, the
// folio outside them, over a hairline as wide as the type area.
const HEAD_Y = 11; // mm from the top edge to the top of the guide words
const [GUIDE, FOLIO] = [10.5, 8]; // pt
const head = (id, content, parity, x, size, extra) => ({ kind: 'text', id, content, parity,
  fontFamily: HEI, fontWeight: 700, fontSize: pt(size), lineHeight: 1, color: col('ink'),
  // A design line puts its baseline 0.8 of its height down: the folio drops to share it.
  placement: { anchor: { to: 'page', edge: parity === 'even' ? 'top-left' : 'top-right' },
    offset: { x: mm(parity === 'even' ? x : -x), y: mm(HEAD_Y + 0.8 * (GUIDE - size) * PT) } },
  ...extra });
const folio = { color: col('muted') };
const guideWords = [
  head('verso-folio', '{pageNumber}', 'even', SIDE, FOLIO, folio),
  head('verso-guide', '{firstMark.h2}—{lastMark.h2}', 'even', SIDE + 8, GUIDE),
  head('recto-guide', '{firstMark.h2}—{lastMark.h2}', 'odd', SIDE + 8, GUIDE),
  head('recto-folio', '{pageNumber}', 'odd', SIDE, FOLIO, folio),
  { kind: 'rule', id: 'hairline', direction: 'horizontal', thickness: pt(0.5), color: col('ink'),
    placement: { anchor: { to: 'page', edge: 'top-left' },
      offset: { x: mm(SIDE), y: mm(HEAD_Y + 5.5) }, size: { width: mm(AREA.width) } } },
];

The first and the last headword of each page in its running head

Ingredients

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

Method

#1 · Guide words from the headwords

The code is the short answer above. Every headword is a level-2 heading, and {firstMark.h2} and {lastMark.h2} print the text of the first and the last level-2 heading that starts on the page (Text elements). The mark is the heading’s characters: ## {天|tiān} marks 天, and the reading stays over the headword. An entry that runs on from one page to the next counts only where its headword stands: page 635 opens with the end of 殄 and is headed 腆—髫. Level 1 is kept for the letters: none opens in these four pages, but a letter head would not count as a guide word.

#2 · Pinyin over the headwords

script.js · lines 82–91in full code
// A heading with no design of its own keeps its reading: '## {天|tiān}' sets tiān over 天.
// Two grid lines hold the headword and a 7.5 pt reading, so every entry stays on the grid.
// A Latin reading stands clear of its base by its descenders: the g of tīng stays off 汀.
const cjk = {
  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES },
  // The regular Song, not the heading's Black: a reading takes the face of its base.
  ruby: { fontFamily: SONG, fontSize: em(0.5), color: col('cinnabar') },
};
const headword = { level: 2, fontSize: pt(15), lineHeight: pt(2 * LEAD), marginTop: pt(0),
  marginBottom: pt(0) };

{天|tiān} is the compact form of :ruby[天]{rt="tiān"}, one reading over one character (Chinese marks, ruby and warichu). A heading with no design of its own sets its reading; a heading design would print 天 alone. The reading takes the heading’s own face, Black, unless cjk.ruby.fontFamily names one, so the regular Song is named. Half of 15 pt is 7.5 pt, and the heading’s 30 pt line leaves room for it over the headword, so the heading is two lines of the grid and the text under it stays on the 15 pt lines of both columns. A pinyin reading is raised by the depth of its face’s descenders and 0.04 em more, so the g of tīng ends 0.6 pt above the em box of 汀.

#3 · One paragraph to an entry

script.js · lines 95–101in full code
// As the Kangxi Dictionary sets an entry: the rhyme-book readings (反切), then the senses
// run in, each after its number. '**②**' marks a number, and the text prints its bold in
// cinnabar: the only bold on these pages. A circled number is a Chinese character to the
// composer: no line ends on one, away from the sense it opens, and no space follows it.
const bodyText = { fontFamily: SONG, fontSize: pt(BODY), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('cinnabar'), italicColor: col('ink'), referenceColor: col('ink'),
  textAlign: 'justify', firstLineIndent: pt(0) }; // no indent: the headword opens the entry

The Kangxi Dictionary runs an entry together: the readings of the rhyme books, then each sense introduced by 又. Here the 又 became circled numbers, typed as **②**, and boldColor prints them in the cinnabar of the headwords; there is no other bold in the text. A sense that the Kangxi reads another way keeps its own reading, as 跳 ② does with 徒刀切. The composer sets ① to ⑳ as Chinese characters: a line never ends on a number whose sense opens the next line, and no Han–Latin space comes between the number and its text, so the numbers are typed as they are. Column balancing is off (headings.balancing.enabled: false), so no column opens space above its headwords and every entry follows the one before it by the same distance.

#4 · The tab of the letter T

script.js · lines 62–78in full code
const INITIALS = 'ABCDEFGHJKLMNOPQRSTWXYZ'; // no pinyin syllable starts with I, U or V
const STEP = AREA.height / INITIALS.length; // mm: 7.13, the 23 tabs fill the type area's height
const tab = (parity) => {
  const edge = parity === 'odd' ? 'top-right' : 'top-left'; // the fore-edge
  const at = (x, width) => ({ anchor: { to: 'page', edge },
    offset: { x: mm(parity === 'odd' ? x : -x), y: mm(TOP + INITIALS.indexOf('T') * STEP + 0.3) },
    size: { width: mm(width), height: mm(STEP - 0.6) } });
  // 6 mm inside the trim and 3 mm past it: the page cuts the tab square at the fore-edge
  // (a print file with cutLines prints the 3 mm in its bleed); the letter on the 6 mm.
  return [
    { kind: 'box', id: `tab-${parity}`, parity, placement: at(3, 9),
      style: { backgroundColor: col('cinnabar'), borderRadius: mm(1.2) } },
    { kind: 'text', id: `tab-letter-${parity}`, parity, content: 'T', fontFamily: HEI,
      fontWeight: 700, fontSize: pt(9), lineHeight: 1, color: col('paper'), align: 'center',
      verticalAlign: 'middle', placement: at(0, 6) },
  ];
};

Pinyin syllables start with 23 of the 26 letters (none with I, U or V), so the type area’s height is cut into 23 steps of 7.13 mm, and T takes the 19th. The tab is 9 mm wide and starts 3 mm past the trim, so the page cuts it square at the fore-edge and only its inner corners show their rounding; a print file with page.cutLines would carry those 3 mm into its bleed. The letter is centred on the 6 mm inside the page. All four pages are in T, so the tab stays at the same height; the Sailor’s Word-Book moves it down the edge from one letter to the next.

#5 · Each face loads its own characters

script.js · lines 284–293in full code
// Fontsource cuts a Chinese face into about a hundred files (gotcha: cjk-fonts-slices).
// The regular Song sets the whole sample; each other voice gets only its own text.
const all = (re) => [...markdown.matchAll(re)].map((m) => m[1]).join('');
const heads = all(/^## \{(.+?)\|/gm);
await loadFonts(FONTS, markdown);
await loadCjkFonts({ [SONG]: ['400'] }, markdown);
await loadCjkFonts({ [SONG]: ['700'] }, all(/\*\*(.+?)\*\*/g));
await loadCjkFonts({ [SONG]: ['900'] }, heads);
await loadCjkFonts({ [HEI]: ['700'] }, `${heads}—0123456789T`);
await loadCjkFonts({ [KAI]: ['400'] }, all(/style="colophon-zh"\}\n(.+)\n/g));

Fontsource cuts each Chinese face into about a hundred files by character range, and loadCjkFonts loads the files that hold the text it is given. The regular Song gets the whole sample, the colophon’s English included. The Black gets the thirty headwords, the bold weight the sense numbers, the Hei the headwords and the digits of the running heads, and the Kai the colophon’s sentence of Chinese. cjkPdfProvider embeds the same files in the PDF, each cut down to the characters its pages use.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 086 · A Chinese dictionary page with guide words ═════════
// https://postext.dev/en/cookbook/chinese-dictionary-page
// Code: MIT · Text: 康熙字典 (1716), Wikisource transcription, CC BY-SA 4.0 · Pinyin: CC BY 4.0
// Fonts: Noto Serif TC, Noto Sans TC, LXGW WenKai TC (SIL OFL 1.1) · Needs postext ≥ 1.25.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 = 'chinese-dictionary-page';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: black and one cinnabar, the second ink of a two-colour dictionary
const palette = {
  ink: '#1f1b17', // text, guide words
  cinnabar: '#a52f28', // headwords, their readings, sense numbers, the thumb tab
  rule: '#bab2a4', // the column rule
  muted: '#5c554d', // folios, colophon
  paper: '#fbf8f2', // the page, and the letter reversed out of the tab
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the cinnabar.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.cinnabar })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [SONG, HEI, KAI] = ['Noto Serif TC', 'Noto Sans TC', 'LXGW WenKai TC'];
const PT = 25.4 / 72; // mm in a point
const [BODY, LEAD] = [9, 15]; // pt: 小五 on a 15 pt line, the grid both columns share
const [CHARS, LINES] = [17, 31]; // characters to a column's line, lines to a column
const TRIM = { width: 140, height: 203 }; // mm: 大32开
const MIN = { top: 20, bottom: 16, side: 12 }; // mm: minimums the grid grows to centre the area
// The type area the grid sets (two columns and a 2-em gutter) and the margins it leaves.
const AREA = { width: (2 * CHARS + 2) * BODY * PT, height: LINES * LEAD * PT }; // 114.3 × 164
const SIDE = (TRIM.width - AREA.width) / 2; // 12.85 mm
const TOP = MIN.top + (TRIM.height - MIN.top - MIN.bottom - AREA.height) / 2; // 21.5 mm

// #region answer: the first and the last headword of each page in its running head
// Each headword is a level-2 heading, '## {天|tiān}'. {firstMark.h2} prints the text of the
// first one that starts on the page, without its reading, and {lastMark.h2} the last; a
// page on which none starts repeats the one in force. They stand at the outer corner, the
// folio outside them, over a hairline as wide as the type area.
const HEAD_Y = 11; // mm from the top edge to the top of the guide words
const [GUIDE, FOLIO] = [10.5, 8]; // pt
const head = (id, content, parity, x, size, extra) => ({ kind: 'text', id, content, parity,
  fontFamily: HEI, fontWeight: 700, fontSize: pt(size), lineHeight: 1, color: col('ink'),
  // A design line puts its baseline 0.8 of its height down: the folio drops to share it.
  placement: { anchor: { to: 'page', edge: parity === 'even' ? 'top-left' : 'top-right' },
    offset: { x: mm(parity === 'even' ? x : -x), y: mm(HEAD_Y + 0.8 * (GUIDE - size) * PT) } },
  ...extra });

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

#First headword on the verso, last on the recto

Some dictionaries print one guide word to a page, the first at the top of the verso and the last at the top of the recto, so the spread reads 天 … 髫.

-  head('verso-guide', '{firstMark.h2}—{lastMark.h2}', 'even', SIDE + 8, GUIDE),
-  head('recto-guide', '{firstMark.h2}—{lastMark.h2}', 'odd', SIDE + 8, GUIDE),
+  head('verso-guide', '{firstMark.h2}', 'even', SIDE + 8, GUIDE),
+  head('recto-guide', '{lastMark.h2}', 'odd', SIDE + 8, GUIDE),

#Pinyin with ɑ and ɡ

Chinese dictionaries set their pinyin in a face with a one-storey a and g. Name Andika for the readings and add it to FONTS ('Andika': ['400'], with its OFL credit).

-  ruby: { fontFamily: SONG, fontSize: em(0.5), color: col('cinnabar') },
+  ruby: { fontFamily: 'Andika', fontSize: em(0.5), color: col('cinnabar') },

#Headwords at text size

A compact dictionary sets the headword in bold at the start of its paragraph. Put the entries in :::paragraphs{style="entry"}, open each with **{天|tiān}** and print {firstMark.entry}: a paragraph that opens with a bold run marks the page with it.

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

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 →

  • With column balancing on, a column that cannot take the next headword with two lines of its text under it (bodyText.widowMinLines) ends early, and the lines left over go above the headwords, one line each at most: one entry stands a line clear of the one before, the next does not. Off, such a column ends short.

Credits

Text
  • Thirty entries of the Kangxi Dictionary (康熙字典, 1716), 天 to 庭, each cut to a few senses: what is kept stands in the source’s order and under its attribution, a sense with a reading of its own keeps it, and of the ancient forms (古文) only 銕 is set, the others being outside the fonts. Variant forms are written in today’s standard Traditional characters and the punctuation is revised in places. From the zh.wikisource transcription, which gives the Siku Quanshu Huiyao copy (四庫全書薈要本) as its source and notes some of Wang Yinzhi’s corrections of 1831 (字典考證); 29 pages by radical and stroke count, revisions read on 29 September 2026: 大部 2535754, 水部/八畫 2542298, 田部 2543683, 心部/六畫 2537571, 土部/十畫 2535684, 門部/十畫 2553837, 心部/四畫 2537569, 歹部/五畫 2541608, 肉部/八畫 2549900, 人部/六畫 416510, 手部/六畫 2538445, 辵部/五畫 2553283, 木部/七畫 2540094, 虫部/八畫 2551174, 言部/八畫 2551690, 髟部/五畫 2556393, 穴部/六畫 2546633, 目部/六畫 2544863, 足部/六畫 2552906, 米部/十九畫 2548884, 巾部/五畫 2536199, 貝部/五畫 2552278, 金部/十三畫 2553630, 食部/九畫 2556072, 水部/二畫 2541898, 耳部/十六畫 2549782, 广部/二十二畫 2536291, 亠部/七畫 409671, 广部/七畫 2536277 · Zhang Yushu, Chen Tingjing and others (1716); transcription by Wikisource editors · CC BY-SA 4.0
  • The pinyin readings, the sense numbers, the order of the entries and the colophon · Postext Cookbook · CC BY 4.0
Fonts
Noto Serif TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1)
SandboxPDF