Em poucas palavras
Uma página de um livro de leitura japonês, com kana pequenos sobre cada kanji para que uma criança leia em voz alta. O Postext põe cada leitura sobre os caracteres e deixa uma longa se apoiar no kana vizinho, nunca em outro kanji.
O que você vai compor
As primeiras páginas de “Gon, a raposa” (ごんぎつね, 1932), de Niimi Nankichi, como as imprime um livro de leitura do quarto ano, o conto que toda criança japonesa conhece aos nove ou dez anos. Uma página B5 leva 28 caracteres por 21 linhas de Klee One, uma fonte desenhada a partir da letra dos livros didáticos, em 14 pt numa linha de 28 pt, com uma leitura em kana pequeno sobre cada kanji. As leituras são o assunto: uma por caractere sobre 村 e 森, uma para a palavra inteira sobre 百舌鳥 (mozu), cujos kanji não têm leitura própria, e leituras jukugo sobre 兵十 (Hyōjū), cada uma sobre o kanji até que uma fique longa demais. Um boxe no fim mostra os três casos para o professor. A cartilha com pinyin põe leituras chinesas sobre cada caractere da mesma forma.
Esta receita responde a
- Como coloco furigana sobre os kanji, uma leitura por caractere ou uma para a palavra inteira?
A resposta curta
// 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
};
Ingredientes
- Funcionalidades
- Furigana: leituras em kana sobre os kanjiRubi: leituras em pinyin e zhuyinKana, kanji e rōmajiMarcas de ênfase japonesas (bōten)Fontes chinesas, japonesas e coreanasGrade de caracteresEspaçamento da pontuação japonesa (yakumono)Quebra de linha em japonês (kinsoku)Títulos sobre linhas do texto (gyōdori)Aberturas desenhadasAtributos de títuloBoxesCabeços e fóliosMargens espelhadasCor do papelEstilos de parágrafoPaleta de cores semânticaImportação do Aozora BunkoExportação para PDF
- Também usa
- Quebra de linha em chinêsEquilíbrio de colunasPontos de ênfase e linhas de nome e de títuloSair da grade de propósitoFontes incorporadas ao PDF
- Tipografia
- Klee One, Zen Maru Gothic (SIL OFL 1.1)
- Materiais
- Nenhum: todas as imagens são desenhadas em código
Preparo
#1 · Três jeitos de escrever uma leitura
O código é a resposta curta logo acima. No Markdown, {村|むら} põe むら sobre 村; {兵十|ひょう|じゅう} dá a cada kanji a própria leitura, e num documento marcado como 'ja' isso é rubi jukugo: as leituras ficam sobre os kanji quando cabem, e uma mais longa pode se apoiar no kanji seguinte da mesma palavra, nunca no de outra. {百舌鳥|もず}, uma leitura para três kanji, é rubi de grupo, distribuído sobre a palavra como um todo. :ruby[菜種]{rt="な たね" mode=jukugo} escreve o último exemplo do boxe na forma de diretiva, que também aceita mode=mono e align (Marcas, rubi e warichu).

#2 · 1:2:1, e leituras que só se apoiam em kana
Os dois ajustes em cjk.ruby são os que 'ja' escolhe por conta própria. align: 'jis' compõe uma leitura mais curta que a base à maneira do JIS X 4051: meia unidade de espaço em cada ponta e uma inteira entre os kana, e assim も e ず ficam sobre as junções de 百舌鳥 na página 25 em vez de se amontoarem no meio. overhang: 'kana' deixa uma leitura mais longa que a base avançar até um caractere de rubi sobre um kana ou sobre o branco de um sinal vizinho, nunca sobre um kanji: ぎつね sobre o 狐 de 「ごん狐」 se apoia em ん e no colchete que vem depois, e o じゅう de 兵十だな em だ. Onde não há kana para apoiar, os kanji se afastam até a largura da leitura. Na borda de uma linha, a leitura fica dentro da medida.

#3 · Uma entrelinha que comporta as leituras
As leituras têm 7 pt, metade dos 14 pt do texto, e a linha tem 28 pt, de modo que os 14 pt entre duas linhas as acomodam com folga e cada linha da grade fica onde está. Se o passo for menor que o texto mais as leituras, a composição avisa com rubyExceedsLeading.
#4 · A abertura não imprime leituras
// 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) } } },
] } };
O título e o nome do autor são texto de design, que não compõe rubi, por isso a leitura de 新美南吉 vai numa linha própria acima do nome, em kana, como os livros de leitura a imprimem. O próprio título está em kana, ごんぎつね, como os livros escolares o escrevem, embora o texto do Aozora o intitule ごん狐.
#5 · Uma cor de destaque, e leituras um tom mais claras
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' } }));
As leituras usam reading, um marrom um grau mais claro que a tinta, para que o olho distinga as duas camadas sem que o kana fique apagado. O vermelho das higanbana que florescem no conto marca o selo, o número de seção e o título do boxe.
A receita completa
// ═══ 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'),
O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)
Variações
#Kana em tamanho normal nas leituras
Livros antigos imprimiam っ e ょ em tamanho normal no rubi, がつこう por がっこう; smallKana: 'full' faz o mesmo e mantém inalterado o texto lido em voz alta e o texto copiado.
- smallKana: 'keep', // ひょう with its small ょ, as today's books print it
+ smallKana: 'full', // ひよう: the small kana at full size, as letterpress books printed them#Centralize todas as leituras
align: 'center' põe uma leitura curta no meio da base, como faz a maioria dos livros chineses; 1:2:1 é o padrão japonês.
- align: 'jis', // a reading shorter than its base: ½ unit at each end, 1 between (1:2:1)
+ align: 'center', // も ず together in the middle of 百舌鳥Erros comuns
Erro comum
Marque um texto japonês como 'ja', nunca com zh-Hans nem LANG
As edições de uma receita são en e es, mas uma amostra japonesa é japonesa nas duas: `locale: LANG` a marcaria como inglês ou espanhol, e uma marcação chinesa a comporia pelas regras chinesas (pontuação Kaiming, kana pequeno livre para começar linha, 图 no lugar de 図, formas chinesas dos glifos no PDF). Desde o postext 1.30 a marcação é também o idioma em que o texto é composto (em que é medido, pintado e incorporado), então qualquer marcação que não seja 'ja' dá outras formas de glifo que não as japonesas (as chinesas, sob uma marcação chinesa) e outras quebras de linha. Escreva 'ja': isso escolhe a região do Japão (quebra de linha e pontuação da JLReq, pontos de ênfase em gergelim, espaçamento dos furigana, rótulos 図 e 表) e desativa a hifenização. O lint reprova um texto com kana sob uma marcação zh ou ko. Quebra de linha em japonês (kinsoku) →
Erro comum
Componha o japonês com uma fonte japonesa
A Noto Serif SC e a TC têm kana, mas desenham os kanji com formas chinesas (直, 骨 e 角 mudam) e o kana com desenho chinês. Componha o texto em Noto Serif JP ou Shippori Mincho B1 e os títulos em Noto Sans JP, carregadas com loadCjkFonts. Os arquivos japoneses do Fontsource não têm hentaigana nem outros kana históricos (U+1B000–1B16F): loadCjkFonts falha com eles e o PDF imprime caixas, então escreva o kana moderno ou inclua nos recursos da receita uma fonte que os tenha. A Shippori Mincho também não tem as vogais com mácron ō e ū: componha o rōmaji com uma fonte latina. Kana, kanji e rōmaji →
Erro comum
Fontes chinesas são carregadas em fatias, pelo bloco cjk
O Fontsource serve uma família chinesa, japonesa ou coreana em cerca de cem arquivos por peso, cada um com um intervalo de caracteres. loadFonts baixa só o arquivo latin, então na tela os caracteres chineses vêm de uma fonte do sistema e são medidos errado, e o fontsourceProvider entrega ao PDF esse arquivo latin, que os imprime como caixas vazias. Inclua o bloco cjk do kit, chame loadCjkFonts(FONTS, markdown) depois de loadFonts (uma vez por voz, com o texto que ela compõe, quando o livro usa várias fontes CJK) e passe a renderToPdf fontProvider: cjkPdfProvider: os dois pegam os arquivos que contêm os caracteres do texto. Fontes chinesas, japonesas e coreanas →
Erro comum
As leituras são impressas no texto, não em designs, legendas nem células
As leituras rubi são desenhadas em parágrafos, títulos, itens de lista, citações e boxes. Um elemento de texto de design (uma abertura, um cabeço, um selo), uma legenda, uma nota de rodapé e uma célula de tabela imprimem os caracteres-base sem as leituras. Um título que precisa do seu pinyin é um título sem design próprio: desenhe o que está em volta dele (uma faixa, o número da lição) com o design do título anterior, cujos elementos com reserve: false são pintados sob o texto de uma abertura span: 'page'. Rubi: leituras em pinyin e zhuyin →
Erro comum
Leia os arquivos do Aozora como CP932, não como Shift_JIS
Os arquivos de texto do Aozora Bunko estão em Windows-31J (CP932). Decodificados como Shift_JIS puro, o travessão ―― sai como travessões U+2014, ~ como o til ondulado 〜, e alguns caracteres da NEC e da IBM falham. Leia-os como cp932 e depois converta a marcação: o rubi entre 《》, as notas [#…] e os gaiji ※[#…] não são Markdown e saem impressos como estão se forem mantidos. O aozora.py da skill faz as duas coisas. Importação do Aozora Bunko →
Aviso de diagramação · rubyExceedsLeading
Leituras encostam na linha vizinha
Por quê. Um parágrafo com leituras rubi acima ou abaixo do texto tem um vão entre linhas mais estreito que as leituras: elas ocupam a entrelinha e encostam na linha vizinha.
Correção. Componha o parágrafo com mais entrelinha (pelo menos o corpo mais `cjk.ruby.fontSize`) ou reduza as leituras. Docs →
- O Aozora Bunko escreve uma única leitura para a palavra inteira, 兵十《ひょうじゅう》, e o conversor a mantém como rubi de grupo,
{兵十|ひょうじゅう}. Para ter rubi jukugo, divida a leitura por kanji à mão:{兵十|ひょう|じゅう}. - Uma leitura só é dividida na barra em uma parte por caractere quando as partes correspondem à base;
{一人|ひ|と|り}tem três partes para dois kanji e é composto como uma leitura para a palavra, que é mesmo o que 一人 pede.
Créditos
- Receita
- Ignacio Ferro
- Texto
- “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) · domínio público
- The readings over every kanji, the box on furigana and the opener’s labels · Postext Cookbook · CC BY 4.0
- Fontes
- Klee One (SIL OFL 1.1) · Zen Maru Gothic (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


