In short
A page from a Japanese school reader, with small kana printed over every kanji so a child can read it aloud. Postext places each reading over its characters and lets a long one lean on the kana beside it, never on another kanji.
What you'll build
The first pages of Niimi Nankichi’s “Gon the Fox” (ごんぎつね, 1932) as a fourth-year school reader prints them, the story every Japanese child meets at nine or ten. A B5 page holds 28 characters by 21 lines of Klee One, a face drawn after the hand of school textbooks, at 14 pt on a 28 pt line, with a reading in small kana over every kanji. The readings are the subject: one per character over 村 and 森, one for the whole word over 百舌鳥 (mozu), whose kanji have no reading of their own, and jukugo readings over 兵十 (Hyōjū), each over its own kanji until one is too long. A box at the end shows the three cases for the teacher. The pinyin primer sets Chinese readings over every character in the same way.
This recipe answers
- How do I add furigana over kanji, one reading per character or one for the whole word?
The short answer
// In a document tagged 'ja' the compact {漢字|かん|じ} (one reading per character) is jukugo
// ruby: each reading stays over its own kanji when it fits, and when one is longer it may run
// onto the next kanji of the same word; a break may fall between the two. {百舌鳥|もず} (one
// reading for the word) is group ruby, spread over the word 1:2:1. :ruby[菜種]{rt="な たね"
// mode=jukugo} says the same as the compact form; mode=mono keeps each reading to its kanji.
const cjk = {
grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES },
ruby: {
fontSize: em(0.5), // 7 pt: half the text, the size JLReq gives furigana
color: col('reading'),
align: 'jis', // a reading shorter than its base: ½ unit at each end, 1 between (1:2:1)
overhang: 'kana', // a longer reading may run one ruby character onto a kana, never a kanji
smallKana: 'keep', // ひょう with its small ょ, as today's books print it
},
};
// The line gap (28 − 14 = 14 pt) holds a 7 pt reading with room to spare: no line moves for one.
const bodyText = {
fontFamily: TEXT, fontSize: pt(SIZE), lineHeight: pt(PITCH), color: col('ink'),
boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
textAlign: 'justify', firstLineIndent: em(1), indentAfterHeading: true,
avoidRunts: true, // no paragraph ends on one character
};
Readings over every kanji: by character, by word, jukugo, JIS 1:2:1
Ingredients
- Features
- Furigana: kana readings over kanjiRuby: pinyin and zhuyin readingsKana, kanji and rōmajiJapanese emphasis marks (bōten)Chinese, Japanese and Korean fontsCharacter gridJapanese punctuation spacing (yakumono)Japanese line breaking (kinsoku)Headings over body lines (gyōdori)Designed openersHeading attributesCallout boxesRunning heads and foliosMirrored marginsPaper colourParagraph stylesSemantic colour paletteAozora Bunko importPDF export
- Also uses
- Chinese line breakingColumn balancingEmphasis dots, name and title linesLeaving the grid on purposeFonts embedded in the PDF
- Type
- Klee One, Zen Maru Gothic (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · Three ways to write a reading
The code is the short answer above. In the Markdown, {村|むら} puts むら over 村; {兵十|ひょう|じゅう} gives each kanji its own reading, and in a document tagged 'ja' that is jukugo ruby: the readings stay over their kanji when they fit, and a longer one may lean onto the next kanji of the same word, never onto another word’s. {百舌鳥|もず}, one reading for three kanji, is group ruby, spread over the word as one. :ruby[菜種]{rt="な たね" mode=jukugo} writes the box’s last example in the directive form, which also takes mode=mono and align (Marks, ruby and warichu).

#2 · 1:2:1, and readings that lean only on kana
The two settings under cjk.ruby are what 'ja' picks by itself. align: 'jis' sets a reading shorter than its base the JIS X 4051 way: half a unit of space at each end and a whole one between the kana, so も and ず sit over the joins of 百舌鳥 on page 25 instead of bunching in its middle. overhang: 'kana' lets a reading longer than its base run up to one ruby character onto a kana or a mark’s blank beside it, never onto a kanji: ぎつね over the 狐 of 「ごん狐」 leans on ん and on the bracket after it, and the じゅう of 兵十だな on だ. Where there is no kana to lean on, the kanji are spread to the reading’s width. At a line’s edge the reading stays inside the measure.

#3 · A line gap that holds the readings
The readings are 7 pt, half the 14 pt text, and the line is 28 pt, so the 14 pt between two lines takes them with room to spare and every line of the grid stays where it is. Set the pitch tighter than the text plus its readings and the build warns rubyExceedsLeading.
#4 · The opener prints no readings
// Design text sets no furigana (gotcha: ruby-not-in-designs): the author's reading is a
// line of its own.
const BAND = 92; // mm from the trim's top
const opener = { enabled: true, minHeight: pt(PITCH * 6), slot: { elements: [
{ kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('straw') },
placement: { anchor: { to: 'page', edge: 'top-left' },
size: { width: 'fill', height: mm(BAND) } } },
{ kind: 'text', id: 'unit', content: '{attr.unit}', fontFamily: ROUND, fontSize: pt(16),
fontWeight: 700, color: col('paper'), align: 'center', verticalAlign: 'middle',
overflow: 'clip', box: { backgroundColor: col('red'), borderRadius: mm(6) },
placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(-2) },
size: { width: mm(12), height: mm(12) } } },
{ kind: 'text', id: 'series', content: '{title}', fontFamily: ROUND, fontSize: pt(9),
fontWeight: 700, letterSpacing: pt(2), color: col('red'), align: 'left',
verticalAlign: 'middle', placement: { anchor: { to: 'container', edge: 'top-left' },
offset: { x: mm(16), y: mm(-2) }, size: { width: mm(80), height: mm(12) } } },
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: ROUND, fontSize: pt(48),
lineHeight: 1.1, fontWeight: 700, color: col('ink'), align: 'left',
placement: { anchor: { to: '#unit', edge: 'below' }, offset: { y: mm(7) } } },
{ kind: 'text', id: 'kana', content: '{attr.kana}', fontFamily: ROUND, fontSize: pt(8),
letterSpacing: pt(1), color: col('muted'), align: 'left',
placement: { anchor: { to: '#title', edge: 'below' }, offset: { y: mm(5) } } },
{ kind: 'text', id: 'author', content: '{attr.author} 作', fontFamily: ROUND,
fontSize: pt(13), fontWeight: 500, color: col('ink'), align: 'left',
placement: { anchor: { to: '#kana', edge: 'below' }, offset: { y: mm(1) } } },
] } };
The title and the author’s name are design text, which sets no ruby, so the reading of 新美南吉 is a line of its own above the name, in kana, as readers print it. The title itself is in kana, ごんぎつね, as the readers write it, though the Aozora text heads it ごん狐.
#5 · One accent, and readings a shade lighter
const palette = {
ink: '#2a2420', // text: a warm near-black
red: '#b2402c', // the one accent: the unit badge, the section numbers, the box title
reading: '#5a4e45', // the furigana, a shade off the ink so the two layers part
straw: '#f6ecd6', // the opener band and the box
muted: '#7a6d62', // folios, the series line, the colophon
paper: '#fffdf8',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.red })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
The readings take reading, a brown a step lighter than the ink, so the eye can tell the two layers apart without the kana growing faint. The red of the higanbana that bloom in the story marks the badge, the section number and the box’s title.
The whole recipe
// ═══ Postext Cookbook · Nº 124 · A school reader with furigana: per character, per word ═══
// https://postext.dev/en/cookbook/jukugo-furigana-textbook
// Code: MIT · Text: 新美南吉「ごん狐」(1932), Aozora Bunko 628 (PD); readings: CC BY 4.0
// Fonts: Klee One, Zen Maru Gothic (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 frame; the story is Japanese in both
const RECIPE = 'jukugo-furigana-textbook';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: an autumn reader: ink, the red of the higanbana, a pale straw ground
const palette = {
ink: '#2a2420', // text: a warm near-black
red: '#b2402c', // the one accent: the unit badge, the section numbers, the box title
reading: '#5a4e45', // the furigana, a shade off the ink so the two layers part
straw: '#f6ecd6', // the opener band and the box
muted: '#7a6d62', // folios, the series line, the colophon
paper: '#fffdf8',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.red })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [TEXT, ROUND] = ['Klee One', 'Zen Maru Gothic']; // 教科書体-like text, rounded gothic
const [SIZE, PITCH] = [14, 28]; // pt: a fourth-year reader's size, on a line twice as tall
const [CHARS, LINES] = [28, 21]; // the type area in characters
// #region answer: readings over every kanji: by character, by word, jukugo, JIS 1:2:1
// In a document tagged 'ja' the compact {漢字|かん|じ} (one reading per character) is jukugo
// ruby: each reading stays over its own kanji when it fits, and when one is longer it may run
// onto the next kanji of the same word; a break may fall between the two. {百舌鳥|もず} (one
// reading for the word) is group ruby, spread over the word 1:2:1. :ruby[菜種]{rt="な たね"
// mode=jukugo} says the same as the compact form; mode=mono keeps each reading to its kanji.
const cjk = {
grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES },
ruby: {
fontSize: em(0.5), // 7 pt: half the text, the size JLReq gives furigana
color: col('reading'),
align: 'jis', // a reading shorter than its base: ½ unit at each end, 1 between (1:2:1)
overhang: 'kana', // a longer reading may run one ruby character onto a kana, never a kanji
smallKana: 'keep', // ひょう with its small ょ, as today's books print it
},
};
// The line gap (28 − 14 = 14 pt) holds a 7 pt reading with room to spare: no line moves for one.
const bodyText = {
fontFamily: TEXT, fontSize: pt(SIZE), lineHeight: pt(PITCH), color: col('ink'),
boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
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
#Full-size kana in the readings
Older books printed っ and ょ full size in ruby, がつこう for がっこう; smallKana: 'full' does the same and leaves the text read aloud and copied unchanged.
- smallKana: 'keep', // ひょう with its small ょ, as today's books print it
+ smallKana: 'full', // ひよう: the small kana at full size, as letterpress books printed them#Centre every reading
align: 'center' puts a short reading in the middle of its base, as most Chinese books do; 1:2:1 is the Japanese default.
- align: 'jis', // a reading shorter than its base: ½ unit at each end, 1 between (1:2:1)
+ align: 'center', // も ず together in the middle of 百舌鳥Pitfalls
Pitfall
Tag a Japanese text 'ja', never zh-Hans or LANG
A recipe's editions are en and es, but a Japanese sample is Japanese in both: `locale: LANG` would tag it English or Spanish, and a Chinese tag would set it by the Chinese rules (Kaiming punctuation, small kana free to start a line, 图 for 図, Chinese glyph forms in the PDF). From postext 1.30 the tag is also the language the text is shaped in (measured, painted and embedded), so any tag but 'ja' gives other glyph forms than the Japanese ones (the Chinese ones under a Chinese tag) and other line breaks. Write 'ja': it picks the Japan region (JLReq line breaking and punctuation, sesame emphasis marks, furigana spacing, 図 and 表 labels) and turns hyphenation off. The lint fails a text with kana under a zh or ko tag. Japanese line breaking (kinsoku) →
Pitfall
Set Japanese in a Japanese face
Noto Serif SC and TC have kana, but they draw the kanji in Chinese forms (直, 骨 and 角 differ) and the kana in a Chinese design. Set the text in Noto Serif JP or Shippori Mincho B1 and the heads in Noto Sans JP, loaded with loadCjkFonts. Fontsource's Japanese files hold no hentaigana or other historic kana (U+1B000–1B16F): loadCjkFonts fails on them and the PDF prints boxes, so write the modern kana or ship a face that has them in the recipe's assets. Shippori Mincho also lacks the macron vowels ō and ū: set rōmaji in a Latin face. Kana, kanji and rōmaji →
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
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
Read Aozora files as CP932, not Shift_JIS
Aozora Bunko's text files are Windows-31J (CP932). Decoded as plain Shift_JIS, the dash ―― comes out as em dashes (U+2014), ~ as the wave dash 〜, and a few NEC and IBM characters fail. Read them as cp932, then convert the markup: ruby in 《》, the [#…] notes and the ※[#…] gaiji are not Markdown and print as they are if left in. The skill's aozora.py does both. Aozora Bunko import →
Layout warning · rubyExceedsLeading
Readings crowd the next line
Why. A paragraph with ruby readings over or under its text has a line gap narrower than the readings: they sit in the leading and touch the line next to them.
Fix. Set the paragraph with more leading (at least the text size plus `cjk.ruby.fontSize`), or make the readings smaller. Docs →
- Aozora Bunko writes one reading for a whole word, 兵十《ひょうじゅう》, and the converter keeps it as group ruby,
{兵十|ひょうじゅう}. For jukugo ruby, split the reading by kanji by hand:{兵十|ひょう|じゅう}. - A reading is split at the bar into one part per character only when the parts match the base;
{一人|ひ|と|り}has three parts for two kanji and is set as one reading for the word, which is what 一人 needs anyway.
Credits
- Recipe
- Ignacio Ferro
- Text
- “Gon gitsune” (ごん狐), section 1, by Niimi Nankichi (1932): Aozora Bunko card 628, base text 新美南吉童話集 (Iwanami Bunko, 1996, second printing 1997), input by 林裕司, proofing by 浜野智 · Niimi Nankichi (1913–1943) · public domain
- The readings over every kanji, the box on furigana and the opener’s labels · Postext Cookbook · CC BY 4.0
- Fonts
- Klee One (SIL OFL 1.1) · Zen Maru Gothic (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


