En pocas palabras
Una página de un libro de lectura japonés, con kana pequeños sobre cada kanji para que un niño la lea en voz alta. Postext pone cada lectura sobre sus caracteres y deja que una larga se apoye en el kana vecino, nunca en otro kanji.
Lo que vas a componer
Las primeras páginas de «Gon, el zorro» (ごんぎつね, 1932), de Niimi Nankichi, como las imprime un libro de lectura de cuarto curso: el cuento que todo niño japonés conoce a los nueve o diez años. Una página B5 lleva 28 caracteres por 21 líneas de Klee One, una letra dibujada a partir de la mano de los libros de texto escolares, a 14 pt sobre una línea de 28 pt, con una lectura en kana pequeño sobre cada kanji. Las lecturas son el tema: una por carácter sobre 村 y 森, una para toda la palabra sobre 百舌鳥 (mozu), cuyos kanji no tienen lectura propia, y lecturas jukugo sobre 兵十 (Hyōjū), cada una sobre su kanji hasta que una no cabe. Un recuadro al final muestra los tres casos para el maestro. La cartilla con pinyin pone lecturas chinas sobre cada carácter de la misma manera.
Esta receta responde a
- ¿Cómo pongo furigana sobre los kanji, una lectura por carácter o una para toda la palabra?
La respuesta corta
// 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
- Funciones
- Furigana: lecturas en kana sobre los kanjiRuby: lecturas en pinyin y zhuyinKana, kanji y rōmajiMarcas de énfasis japonesas (bōten)Fuentes chinas, japonesas y coreanasRetícula de caracteresEspaciado de la puntuación japonesa (yakumono)Corte de líneas japonés (kinsoku)Títulos que ocupan líneas del texto (gyōdori)Aperturas diseñadasAtributos de títuloRecuadrosCabeceras y foliosMárgenes simétricosColor del papelEstilos de párrafoPaleta de color semánticaImportar textos de Aozora BunkoExportación a PDF
- También usa
- Corte de líneas en chinoEquilibrado de columnasPuntos de énfasis y líneas de nombre y de títuloSalir de la rejilla a propósitoFuentes incrustadas en el PDF
- Tipografía
- Klee One, Zen Maru Gothic (SIL OFL 1.1)
- Recursos
- Ninguno: todas las imágenes se dibujan en código
Elaboración
#1 · Tres maneras de escribir una lectura
El código es la respuesta corta de arriba. En el Markdown, {村|むら} pone むら sobre 村; {兵十|ひょう|じゅう} da a cada kanji su propia lectura, y en un documento con la etiqueta 'ja' eso es ruby jukugo: las lecturas se quedan sobre sus kanji cuando caben, y una más larga puede apoyarse en el kanji siguiente de la misma palabra, nunca en el de otra. {百舌鳥|もず}, una lectura para tres kanji, es ruby de grupo, repartido sobre la palabra entera. :ruby[菜種]{rt="な たね" mode=jukugo} escribe el último ejemplo del recuadro con la directiva, que también admite mode=mono y align (Marcas, ruby y warichu).

#2 · 1:2:1, y lecturas que solo se apoyan en kana
Los dos ajustes bajo cjk.ruby son los que 'ja' elige por sí solo. align: 'jis' compone una lectura más corta que su base al modo de JIS X 4051: medio hueco en cada extremo y uno entero entre los kana, de modo que も y ず quedan sobre las uniones de 百舌鳥 en la página 25 en lugar de amontonarse en el centro. overhang: 'kana' deja que una lectura más larga que su base invada hasta un carácter de ruby de un kana o del blanco de un signo vecino, nunca de un kanji: ぎつね sobre el 狐 de 「ごん狐」 se apoya en ん y en el corchete que lo sigue, y el じゅう de 兵十だな en だ. Donde no hay kana en que apoyarse, los kanji se separan hasta el ancho de la lectura. En el borde de una línea, la lectura no sale de la medida.

#3 · Un interlineado que deja sitio a las lecturas
Las lecturas miden 7 pt, la mitad de los 14 pt del texto, y la línea 28 pt, así que los 14 pt entre dos líneas las alojan con holgura y todas las líneas de la retícula se quedan en su sitio. Si el paso es menor que el texto más sus lecturas, la composición avisa con rubyExceedsLeading.
#4 · La apertura no imprime lecturas
// 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) } } },
] } };
El título y el nombre del autor son texto de diseño, que no compone ruby, así que la lectura de 新美南吉 va en una línea propia sobre el nombre, en kana, como la imprimen los libros de lectura. El título mismo va en kana, ごんぎつね, como lo escriben los libros escolares, aunque el texto de Aozora lo encabeza ごん狐.
#5 · Un acento, y lecturas un tono más 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' } }));
Las lecturas toman reading, un marrón un paso más claro que la tinta, para que la vista distinga las dos capas sin que el kana se vuelva pálido. El rojo de las higanbana que florecen en el cuento marca la insignia, el número de sección y el título del recuadro.
La receta 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 = 'es'; // @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'),
El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)
Variantes
#Kana de tamaño completo en las lecturas
Los libros antiguos imprimían っ y ょ a tamaño completo en el ruby, がつこう por がっこう; smallKana: 'full' hace lo mismo y deja sin cambios el texto que se lee en voz alta y el que se copia.
- smallKana: 'keep', // ひょう with its small ょ, as today's books print it
+ smallKana: 'full', // ひよう: the small kana at full size, as letterpress books printed them#Centra todas las lecturas
align: 'center' pone una lectura corta en el centro de su base, como hacen casi todos los libros chinos; 1:2:1 es lo habitual en 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 百舌鳥Errores frecuentes
Error frecuente
Etiqueta un texto japonés 'ja', nunca zh-Hans ni LANG
Las ediciones de una receta son en y es, pero una muestra japonesa es japonesa en las dos: `locale: LANG` la etiquetaría como inglés o español, y una etiqueta china la compondría con las reglas chinas (puntuación Kaiming, kana pequeño libre de empezar línea, 图 en lugar de 図, formas chinas de los caracteres en el PDF). Desde postext 1.30 la etiqueta es además el idioma en el que se compone el texto (en el que se mide, se pinta y se incrusta), así que cualquier etiqueta que no sea 'ja' da otras formas de glifo que las japonesas (las chinas, con una etiqueta china) y otros cortes de línea. Escribe 'ja': elige la región de Japón (corte y puntuación de la JLReq, puntos de sésamo, reparto de los furigana, etiquetas 図 y 表) y desactiva la separación silábica. El lint falla un texto con kana bajo una etiqueta zh o ko. Corte de líneas japonés (kinsoku) →
Error frecuente
Compón el japonés con una fuente japonesa
Noto Serif SC y TC tienen kana, pero dibujan los kanji con formas chinas (直, 骨 y 角 cambian) y el kana con un diseño chino. Compón el texto en Noto Serif JP o Shippori Mincho B1 y los títulos en Noto Sans JP, cargadas con loadCjkFonts. Los archivos japoneses de Fontsource no tienen hentaigana ni otros kana históricos (U+1B000–1B16F): loadCjkFonts falla con ellos y el PDF imprime cajas, así que escribe el kana moderno o lleva en los recursos de la receta una fuente que los tenga. Shippori Mincho tampoco tiene las vocales con macrón ō y ū: compón el rōmaji con una fuente latina. Kana, kanji y rōmaji →
Error frecuente
Las fuentes chinas se cargan por fragmentos, con el bloque cjk
Fontsource sirve una familia china, japonesa o coreana en un centenar de archivos por peso, cada uno con un intervalo de caracteres. loadFonts solo descarga el archivo latin, así que en pantalla los caracteres chinos salen de una fuente del sistema y se miden mal, y fontsourceProvider entrega al PDF ese archivo latin, que los imprime como cajas vacías. Añade el bloque cjk del kit, llama a loadCjkFonts(FONTS, markdown) después de loadFonts (una vez por voz, con el texto que compone, si el libro usa varias fuentes chinas) y pasa a renderToPdf fontProvider: cjkPdfProvider: ambos toman los archivos que contienen los caracteres del texto. Fuentes chinas, japonesas y coreanas →
Error frecuente
Las lecturas se imprimen en el texto, no en diseños, pies ni celdas
Las lecturas ruby se dibujan en párrafos, títulos, elementos de lista, citas y recuadros. Un elemento de texto de un diseño (una apertura, una cabecera, una etiqueta), un pie, una nota al pie y una celda de tabla imprimen los caracteres base sin sus lecturas. Un título que necesita su pinyin es un título sin diseño propio: dibuja lo que lo rodea (una banda, el número de la lección) con el diseño del título anterior, cuyos elementos con reserve: false se pintan bajo el texto de una apertura span: 'page'. Ruby: lecturas en pinyin y zhuyin →
Error frecuente
Lee los archivos de Aozora como CP932, no como Shift_JIS
Los archivos de texto de Aozora Bunko están en Windows-31J (CP932). Leídos como Shift_JIS a secas, la raya ―― sale como rayas U+2014, ~ como el guion ondulado 〜, y algunos caracteres de NEC e IBM fallan. Léelos como cp932 y convierte después el marcado: el ruby entre 《》, las notas [#…] y los gaiji ※[#…] no son Markdown y se imprimen tal cual si se dejan. aozora.py, de la skill, hace las dos cosas. Importar textos de Aozora Bunko →
Aviso de maquetación · rubyExceedsLeading
Lecturas pegadas a la línea vecina
Por qué. Un párrafo con lecturas ruby encima o debajo del texto tiene un hueco entre líneas más estrecho que las lecturas: ocupan el interlineado y tocan la línea vecina.
Solución. Compón el párrafo con más interlineado (al menos el cuerpo más `cjk.ruby.fontSize`), o reduce las lecturas. Documentación →
- Aozora Bunko escribe una sola lectura para toda la palabra, 兵十《ひょうじゅう》, y el conversor la conserva como ruby de grupo,
{兵十|ひょうじゅう}. Para tener ruby jukugo, divide la lectura por kanji a mano:{兵十|ひょう|じゅう}. - Una lectura se reparte por la barra en una parte por carácter solo cuando las partes casan con la base;
{一人|ひ|と|り}tiene tres partes para dos kanji y se compone como una lectura para la palabra, que es lo que 一人 necesita.
Créditos
- Receta
- Ignacio Ferro
- Texto
- «Gon gitsune» (ごん狐), sección 1, de Niimi Nankichi (1932): ficha 628 de Aozora Bunko, texto base 新美南吉童話集 (Iwanami Bunko, 1996, segunda tirada 1997), transcripción de 林裕司, corrección de 浜野智 · Niimi Nankichi (1913–1943) · dominio público
- Las lecturas sobre cada kanji, el recuadro sobre el furigana y los rótulos de la apertura · Postext Cookbook · CC BY 4.0
- Fuentes
- Klee One (SIL OFL 1.1) · Zen Maru Gothic (SIL OFL 1.1)
- Código
- MIT, como Postext
Editar este texto ↗ (se abre en una nueva pestaña)Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)


