简单来说
日本小学国语读本里的一页,每个汉字上方都印着小号假名,方便孩子朗读。Postext把每个读音放在对应的字上方,较长的读音可以伸到旁边的假名上,但不会压到别的汉字。
成品一览
新美南吉的《小狐狸阿权》(ごんぎつね,1932)开头几页,照小学四年级国语读本的样子排出,日本孩子九、十岁时都会读到这个故事。B5页面上每行28字,每页21行,字体是Klee One,一款照着教科书手写体设计的字体,字号14 pt,行距28 pt,每个汉字上方都有小号假名读音。读音是这里的主题:村和森上是单字读音;百舌鳥(mozu)的三个字没有各自的读音,所以整个词上标一个读音;兵十(Hyōjū)上是熟语读音,每个读音留在自己的字上方,直到某一个太长为止。末尾一个标注框把这三种情况列给老师看。拼音识字课本用同样的方法在每个汉字上方标拼音。
这道食谱解答
- 怎样在汉字上加振假名,是一字一音还是整个词一个读音?
简短回答
// 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
};
用料
做法
#1 · 读音的三种写法
代码就是上面的简短回答。在Markdown里,{村|むら}把むら放在村的上方;{兵十|ひょう|じゅう}给每个汉字一个读音,在标为'ja'的文档里,这就是熟语注音(熟語ルビ):读音放得下时各自留在自己的字上方,较长的读音可以伸到同一个词的下一个汉字上,但不会伸到别的词上。{百舌鳥|もず}是三个汉字共用一个读音,即词组注音(グループルビ),作为一个整体分布在整个词上。:ruby[菜種]{rt="な たね" mode=jukugo}用指令写出标注框里的最后一个例子,这种写法还接受mode=mono和align(着重号、注音与夹注)。

#2 · 1:2:1,读音只伸到假名上
cjk.ruby下的两项设置,'ja'本来就会选。align: 'jis'按JIS X 4051排比基字短的读音:两端各空半个单位,假名之间空一个单位,所以在第25页上,も和ず分别落在百舌鳥字与字的交界处上方,不会挤在中间。overhang: 'kana'允许比基字长的读音伸出去,最多一个注音字宽,压在旁边的假名或标点的空白上,但不压汉字:「ごん狐」里狐上方的ぎつね伸到ん和后面的引号上,兵十だな里的じゅう伸到だ上。旁边没有假名可以伸时,就把汉字拉开到读音的宽度。在行首或行尾,读音不超出行长。

#3 · 容得下读音的行距
读音7 pt,是14 pt正文的一半,行距28 pt,所以两行之间的14 pt放得下读音,还有余量,字格上的每一行都不移动。如果行距小于正文加读音的高度,排版时会报告rubyExceedsLeading。
#4 · 章首页不印读音
// 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) } } },
] } };
标题和作者名是设计文字,设计文字不排注音,所以新美南吉的读音单独占一行,用假名排在名字上方,读本就是这样印的。标题本身也用假名写成ごんぎつね,和读本一致,尽管青空文库的文本把题目写作ごん狐。
#5 · 一个强调色,读音的颜色浅一级
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' } }));
读音用reading,一种比正文墨色浅一级的棕色,读者能分清两层文字,假名又不至于淡到看不清。故事里开着的彼岸花的红色,用在徽标、节号和标注框的标题上。
完整食谱
// ═══ 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'),
组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)
变化
#读音里的小写假名排成大字
旧书在注音里把っ和ょ排成大字,がっこう印作がつこう;smallKana: 'full'照此处理,朗读和复制出来的文字不变。
- smallKana: 'keep', // ひょう with its small ょ, as today's books print it
+ smallKana: 'full', // ひよう: the small kana at full size, as letterpress books printed them#所有读音居中
align: 'center'把较短的读音放在基字正中,大多数中文书的拼音就是这样排的;1:2:1是日文的默认做法。
- align: 'jis', // a reading shorter than its base: ½ unit at each end, 1 between (1:2:1)
+ align: 'center', // も ず together in the middle of 百舌鳥常见问题
易错点
日文文本标记为'ja',不要用zh-Hans或LANG
食谱的版本是en和es,但日文示例在两个版本里都是日文:`locale: LANG`会把它标记为英文或西班牙文,中文标记则会按中文规则排它(开明式标点、小假名可以出现在行首、图代替図、PDF中用中文字形)。postext 1.30起,这个标记也是文字成形所用的语言(测量、绘制和嵌入都按它进行),所以'ja'以外的标记给出的不是日文字形(中文标记给出中文字形),断行的位置也不同。写'ja':它选用日本地区(JLReq断行和标点、芝麻着重号、振假名的分布、図和表标签),并关闭断词。lint会让带假名却标记为zh或ko的文本失败。 日文禁则处理 →
易错点
日文要用日文字体排
Noto Serif SC和TC里有假名,但汉字是中文字形(直、骨、角都不同),假名也是中文字体的设计。正文用Noto Serif JP或Shippori Mincho B1,标题用Noto Sans JP,用loadCjkFonts加载。Fontsource的日文文件里没有变体假名等历史假名(U+1B000–1B16F):loadCjkFonts遇到它们会失败,PDF里印出空框,所以要写现代假名,或者把含有这些字的字体放进食谱的assets。Shippori Mincho也没有带长音符号的ō和ū:罗马字要用拉丁字体排。 假名、汉字与罗马字 →
易错点
中文字体通过cjk块分片加载
Fontsource把一个中文、日文或韩文字体家族按每个字重约一百个文件提供,每个文件覆盖一段字符范围。loadFonts只获取latin文件,所以屏幕上的汉字来自系统字体,测量不准;fontsourceProvider交给PDF的也是这个latin文件,汉字印出来是空框。列出kit中的cjk块,在loadFonts之后调用loadCjkFonts(FONTS, markdown)(书中用到几种CJK字体时,每种字体调用一次,并传入它所排的文字),并给renderToPdf传fontProvider: cjkPdfProvider:两者都会取用包含文中字符的那些文件。 中日韩字体 →
易错点
注音印在正文中,不印在设计元素、题注或单元格中
注音会绘制在段落、标题、列表项、引文和框中。设计文本元素(章首页、书眉、徽标)、题注、脚注和表格单元格只印出基字,不带注音。需要拼音的标题应当是一个没有自身设计的标题:把它周围的内容(色带、课次编号)画在它前面那个标题的设计里,该设计中reserve: false的元素会画在span: 'page'章首页的文字下层。 注音:拼音与注音符号 →
易错点
按CP932而不是Shift_JIS读取青空文库文件
青空文库的文本文件是Windows-31J(CP932)编码。如果按普通Shift_JIS解码,――会变成U+2014的破折号,~会变成波浪号〜,一些NEC和IBM扩展字符会出错。要按cp932读取,再转换标记:《》中的注音、[#…]注记和※[#…]外字都不是Markdown,留着就会原样印出来。技能中的aozora.py两件事都做。 导入青空文库文本 →
版面警告 · rubyExceedsLeading
注音挤到相邻的行
原因. 在文字上方或下方带注音的段落,行间空隙比注音还窄:注音位于行距之中,碰到相邻的行。
解决. 给该段落设更大的行距(至少为正文字号加上`cjk.ruby.fontSize`),或把注音缩小。 文档 →
- 青空文库给整个词写一个读音,兵十《ひょうじゅう》,转换器把它保留为词组注音
{兵十|ひょうじゅう}。要排熟语注音,就得手动把读音按汉字拆开:{兵十|ひょう|じゅう}。 - 只有拆出的段数与基字字数相符时,读音才会按竖线拆成每字一段;
{一人|ひ|と|り}两个汉字有三段,所以整个词排一个读音,而一人本来就需要这样排。
致谢
- 文本
- “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) · 公有领域
- The readings over every kanji, the box on furigana and the opener’s labels · Postext Cookbook · CC BY 4.0
- 字体
- Klee One (SIL OFL 1.1) · Zen Maru Gothic (SIL OFL 1.1)


