Skip to main content
Recipe number 126

Cookbook · Chapter 5 · Book structure

A Japanese index in gojūon order, by reading

A chapter on Japanese typesetting terms and its index: each mark gives its reading by furigana or yomi, and the entries file under あ行, か行, さ行 in JIS order.

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

pp. 10–11 · 2–3 of 3

  • Trim 148 × 210 mm
  • 1 column
  • Noto Serif JP 9/16
  • Noto Sans JP
  • 3 pages
  • Level
  • Postext 1.65.0
  • Laid out in 108 ms
  • 122 lines of code

In short

A short chapter that explains the words Japanese typesetters use, with an index at the back. Each indexed word carries its pronunciation, and Postext uses it to sort the index in the Japanese kana order, under row heads あ行, か行 and so on.

What you'll build

A chapter of an invented handbook of Japanese typesetting, 組版の言葉 (The Words of Typesetting), and its index. The chapter explains the names of the parts of a page, of type sizes and of punctuation rules, on an A5 page of 36 characters by 28 lines; each term is marked for the index where it is explained. The index is the subject: Japanese has no alphabetical order for kanji, so an index files each entry by its reading in kana, in the order of the gojūon (五十音) table, under row heads あ行, か行, さ行. A term with furigana gives its reading by itself; any other term with a kanji says it in a yomi attribute. The Chinese name index sorts Chinese names by pinyin and by strokes instead.

This recipe answers

  • How do I sort a Japanese index in gojūon order by its readings?

The short answer

script.js · lines 30–42in full code
// Each mark gives the reading the entry sorts by. A term written with furigana gives it
// itself: :index[{版面|はん|めん}] files 版面 as はんめん. Any other term with a kanji says it
// with yomi: :index[明朝体]{yomi="みんちょうたい"}. Kana and Latin terms need nothing. The
// reading orders the entries in JIS X 4061 order (katakana as hiragana, small kana as large,
// voiced after plain, ー as the vowel before it); Latin terms come first, under A to Z.
const index = {
  groupBy: 'gojuon', // what 'auto' picks in a 'ja' document: heads あ行 か行 さ行 …
  fontFamily: MINCHO, fontSize: pt(8.5), lineHeight: pt(14),
  separator: ' ', locatorSeparator: '、', // 版面 3、5: an ideographic space, then 、
  see: { italic: false }, // → ルビ, → 柱も見よ: upright, no italic in Japanese
  groups: { fontFamily: GOTHIC, fontSize: pt(9), fontWeight: 700, color: col('vermilion'),
    marginTop: pt(7) },
};

The index in gojūon order: by reading, under あ行 か行 さ行…

Ingredients

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

Method

#1 · A reading for every term with a kanji

The code is the short answer above. In the text, :index[{版面|はん|めん}]{main} prints 版面 with はんめん over it and files the entry as はんめん; :index[明朝体]{yomi="みんちょうたい" main} prints no reading and files it as みんちょうたい. Terms in kana, ノンブル or のど, and Latin terms, DTP or JIS X 4051, need nothing (Index marks). The reading decides only the order: the entry prints as written. Kanji readings cannot be guessed, since 天 is てん here and あめ elsewhere, so the engine never tries.

#2 · JIS order and row heads

groupBy: 'gojuon' is what 'auto' picks for locale: 'ja'. The entries sort in the order of JIS X 4061: katakana as hiragana, small kana as large, a voiced kana right after its plain one, ー as the vowel before it. So 級 (きゅう) comes before 行取り (ぎょうどり), and ゴシック体 (ごしっくたい) after 小口 (こぐち). Latin terms come first, under their letters, as JIS orders them; symbols and digits would come before them (Back-of-book index).

Page 11: Latin terms under D and J, then the kana rows か行 to わ行, each entry by its reading.

#3 · → and も見よ

A see reference is a mark with see, :index{term="振り仮名" yomi="ふりがな" see="ルビ"}, and prints 振り仮名 →ルビ. A see-also reference uses seealso and prints the targets before も見よ, 級 10 →歯も見よ, as Japanese indexes word it. see: { italic: false } keeps the labels upright, since a Japanese face has no italic. The ideographic space after each term and the 、 between pages come from separator and locatorSeparator.

#4 · The index across two columns

script.js · lines 46–60in full code
const band = { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
  placement: { anchor: { to: 'page', edge: 'top-left' },
    size: { width: 'fill', height: mm(56) } } };
const opener = (sink, ground = []) => ({ enabled: true, minHeight: pt(PITCH * sink),
  slot: { elements: [...ground,
  { kind: 'text', id: 'kicker', content: '{attr.kicker}', fontFamily: GOTHIC, fontSize: pt(9),
    fontWeight: 700, letterSpacing: pt(2), color: col('vermilion'), align: 'left',
    placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(10) } } },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: GOTHIC, fontSize: pt(22),
    fontWeight: 700, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { anchor: { to: '#kicker', edge: 'below' }, offset: { y: mm(3) } } },
  { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(1.5),
    color: col('vermilion'), placement: { anchor: { to: '#title', edge: 'below' },
      offset: { y: mm(4) }, size: { width: mm(12) } } },
] } });

The index heading is a heading style with span: 'page' and a two-column layout: its design, a pale band with the title, spans the page, and :::index flows in two columns under it. The row heads are set in the vermilion gothic, the entries in the text’s mincho at 8.5 pt on a 14 pt line.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 126 · A Japanese index in gojūon order, read from its readings ═══
// https://postext.dev/en/cookbook/gojuon-index
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Noto Serif JP, Noto Sans JP (SIL OFL 1.1) · Needs postext ≥ 1.28.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 chapter is Japanese in both
const RECIPE = 'gojuon-index';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: ink, one vermilion for the row heads and the chapter label, pale rules
const palette = {
  ink: '#211e1c', // text: a warm near-black
  vermilion: '#b33a22', // the one accent: あ行 heads, the kicker, folios
  tint: '#f5ece6', // the index heading's band
  rule: '#d3c8c0', // the rule under each title
  muted: '#6c625b', // running heads, the colophon
  paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.vermilion })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [MINCHO, GOTHIC] = ['Noto Serif JP', 'Noto Sans JP'];
const [BODY, PITCH] = [9, 16]; // pt: 9 pt text on a 16 pt line
const [CHARS, LINES] = [36, 28]; // the type area in characters

// #region answer: the index in gojūon order: by reading, under あ行 か行 さ行…
// Each mark gives the reading the entry sorts by. A term written with furigana gives it
// itself: :index[{版面|はん|めん}] files 版面 as はんめん. Any other term with a kanji says it
// with yomi: :index[明朝体]{yomi="みんちょうたい"}. Kana and Latin terms need nothing. The
// reading orders the entries in JIS X 4061 order (katakana as hiragana, small kana as large,
// voiced after plain, ー as the vowel before it); Latin terms come first, under A to Z.
const index = {
  groupBy: 'gojuon', // what 'auto' picks in a 'ja' document: heads あ行 か行 さ行 …
  fontFamily: MINCHO, fontSize: pt(8.5), lineHeight: pt(14),
  separator: ' ', locatorSeparator: '、', // 版面 3、5: an ideographic space, then 、
  see: { italic: false }, // → ルビ, → 柱も見よ: upright, no italic in Japanese
  groups: { fontFamily: GOTHIC, fontSize: pt(9), fontWeight: 700, color: col('vermilion'),
    marginTop: pt(7) },
};
// #endregion

// #region opener: the chapter label, the title and a short rule; the index's on a band
const band = { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
  placement: { anchor: { to: 'page', edge: 'top-left' },
    size: { width: 'fill', height: mm(56) } } };

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

#Heads by the first kana

'kana' heads each group with the entry’s first kana, as dictionaries and long name indexes do: か, き, く instead of one か行.

-  groupBy: 'gojuon', // what 'auto' picks in a 'ja' document: heads あ行 か行 さ行 …
+  groupBy: 'kana', // heads か き く け こ…

#A reading without furigana in the text

To keep a term’s first mention bare and still give its reading, move the reading to yomi.

-ページのうち、本文が組まれる範囲を:index[{版面|はん|めん}]{main}という。
+ページのうち、本文が組まれる範囲を:index[版面]{yomi="はんめん" main}という。

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

Chinese has no italic

The CJK families ship no italic, and Chinese typography marks emphasis with dots beside the characters, not with a slant. In a document tagged Chinese, *…* sets emphasis dots on the Chinese characters it holds and keeps italics for the Latin words (cjk.emphasis: 'dots', the default for Chinese); :dots[…] sets them anywhere. With cjk.emphasis: 'italic', or in a document tagged en or es, *…* makes the canvas slant the upright glyphs, a synthetic oblique that Chinese typography never uses (the PDF falls back to the upright face): keep the Chinese tag, or set emphasis in bold or in a Kai face (LXGW WenKai) through a paragraph or chip style. Chinese, Japanese and Korean fonts →

Layout warning · indexReadingMissing

Index entry without a reading

Why. A Japanese index files entries by their reading, and no algorithm reads kanji reliably: this entry has a kanji and none of its marks gives a reading (yomi, kana ruby on the marked text, or a kana sort key), so it files after the kana entries, by code point.

Fix. Add yomi="…" with the reading in kana to one of the entry's marks (:index[東京]{yomi="とうきょう"}), or mark text that carries ruby ({東京|とう|きょう}). Docs →

  • A term with a kanji and no reading raises indexReadingMissing. Without its yomi, 明朝体 dropped to the end of the index, after わ行, with no head, and the build warned that the entry “has a kanji and no reading”.
  • :ruby[…] inside :index[…] needs its brackets escaped, because the mark ends at the first ]; write the compact form, {版面|はん|めん}.
  • A ruby reading counts only when it covers every kanji of the term: :index[行{取|ど}り] leaves 行 unread and warns. {行取|ぎょう|ど}り gives ぎょうどり.

Credits

Text
Original prose, CC BY 4.0
Fonts
Noto Serif JP (SIL OFL 1.1) · Noto Sans JP (SIL OFL 1.1)
SandboxPDF