Skip to main content
Recipe number 127

Cookbook · Chapter 2 · Type & text

A hiragana picture book, spaced by phrase

A vertical picture book in hiragana with a space between phrases (wakachigaki): keep-all keeps each phrase whole, so lines break only at the spaces.

On this page
Output
Canvas · PDF
Postext
Tested with Postext 1.65.0
Needs ≥ 1.25.0 · postext-pdf ≥ 1.25.0
Licence
Updated 10 Oct 2026
Code MIT · Text CC BY 4.0
  • Trim 260 × 200 mm
  • Column and a half, 14.1 mm gutter
  • Klee One 20/36
  • Zen Maru Gothic
  • 10 pages
  • Level
  • Postext 1.57.1
  • Laid out in 46 ms
  • 136 lines of code

In short

A Japanese picture book for small children, all in hiragana, with a space after each group of words and lines that never split one, under a picture on every page.

What you'll build

A ten-page picture book, かみの ふね (The Paper Boat), written for the recipe and illustrated with ten paintings: a girl folds a red paper boat after the rain, and the boat travels down the river past a frog, a heron and the moon to the sea. It is set the way Japanese books for the youngest readers are set: hiragana only, 20 pt in Klee One, a hand modelled on the school textbook face, and a space between phrases, 分かち書き (wakachigaki), so a child reads one phrase at a time. The pages are landscape, 260 × 200 mm, vertical and bound on the right: the picture across the top of the page, short lines of eight characters under it, and the boat travelling leftward, as the pages turn.

This recipe answers

  • How do I space a Japanese picture book by phrases (wakachigaki), with lines that break only at the spaces?
  • Why may small kana, ー and closing brackets not start a line of Japanese, and how do I choose how strict the rule is?
  • Which fonts set Japanese, with kanji in their Japanese forms, on screen and in the PDF?

The short answer

script.js · lines 40–50in full code
// The story is typed with an ordinary space (U+0020) after each phrase (文節). Japanese
// text may break between any two kana, so the space alone does not keep a phrase whole:
// keep-all drops the breaks between two letters and keeps those at a space, after 、。」
// and before 「. Kinsoku still applies.
const phrases = { wordBreak: 'keep-all' }; // cjk.wordBreak
const bodyText = {
  fontFamily: HAND, fontSize: pt(BODY), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  // Ragged: a justified line would stretch its spaces and its kana to fill the tier.
  textAlign: 'left', firstLineIndent: em(0),
};

わかち書き — a space between phrases, and lines that break only there

Ingredients

Type
Klee One, Zen Maru Gothic (SIL OFL 1.1)
Assets
  • bridge-1400.jpg
  • cover-1430.jpg
  • dusk-1400.jpg
  • frog-1400.jpg
  • heron-1400.jpg
  • night-1400.jpg
  • rain-1400.jpg
  • sea-1400.jpg
  • stream-1400.jpg
  • window-1400.jpg
  • The cover: a red paper boat on a river through green meadows, a clear sky on the right for the title (Generated With Diffusion Models, original)
  • Mii-chan folding the red paper boat at a low table by the window, after the rain (Generated With Diffusion Models, original)
  • Mii-chan waving goodbye to the boat on the stream (Generated With Diffusion Models, original)
  • A frog on a stone talking to the boat (Generated With Diffusion Models, original)
  • The boat under a wooden footbridge, little fish following it (Generated With Diffusion Models, original)
  • A white heron on the bank watching the boat on the wide river (Generated With Diffusion Models, original)
  • Dusk: a pink sky over the river mouth and the sea beyond (Generated With Diffusion Models, original)
  • Night: the full moon's reflection lighting the boat's way (Generated With Diffusion Models, original)
  • The boat at sea, greeted by seagulls (Generated With Diffusion Models, original)
  • Mii-chan at her window, looking towards the distant sea (Generated With Diffusion Models, original)

Method

#1 · Keep each phrase whole

The code is the short answer above. Japanese text may break between any two kana, so a space between phrases only adds room; on its own it does not stop a line from ending inside あか|い. cjk.wordBreak: 'keep-all' keeps only the breaks at a space and next to punctuation, after 、。」 or before 「, as CSS word-break: keep-all does, and the kinsoku rules still apply (East Asian typography). The space is an ordinary U+0020, 0.35 em in Klee One, and a line drops it at its end. A U+3000 is a phrase break too, but a fixed character one em wide, kept at the end of the line.

Page 3: eight lines, each ending at a space or after 」 and 、: 「いって / らっしゃい。」 / みいちゃんが / そっと てを…

The text is set ragged. Justified, a short line would stretch its spaces and the gaps between its kana to reach the foot of the tier; a picture book sets each line where its last phrase ends.

#2 · Put the pictures in a tier above the text

script.js · lines 54–62in full code
// In vertical text 'left' is the top of the page: the side column is a tier that takes
// the pictures (floats), and the text runs in the tier under it, right to left.
const layout = {
  layoutType: 'oneAndHalf', writingMode: 'vertical-rl', sideColumnRole: 'floats',
  sideColumnSide: 'left', sideColumnPercent: 58, gutterWidth: pt(2 * BODY),
};
const cjk = { ...phrases, grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES } };
const resourceTypes = [{ id: 'picture', name: 'え', shortLabel: 'え', numberingTemplate: '{n}',
  resetOn: 'never', counterFormat: 'decimal', captionPrefix: '' }]; // pictures, no captions

In vertical text 'left' is the top of the page, so a column-and-a-half layout with its side column on the left is two tiers: the pictures float into the upper tier (14 characters deep), and the text runs in the lower one (8 characters). Each page cites its picture with ::resource{id="…"} and ends with :::pagebreak. The picture type has no caption prefix, and the pictures are 2.186 times as wide as they are tall, the shape of the tier, so each fills it (vertical writing).

#3 · Make the cover a full-page picture

script.js · lines 66–83in full code
// In the flow frame of a vertical page x runs down the sheet and y leftward from its right
// edge; a box's width runs down the sheet.
const at = (down, across) => ({ anchor: { to: 'page', edge: 'top-left' },
  offset: { x: mm(down), y: mm(across) } });
const cover = {
  id: 'cover', numbered: false, toc: false, span: 'page', header: { elements: [] },
  breakBefore: { enabled: true, parity: 'any' },
  advancedDesign: { enabled: true, minHeight: mm(TRIM.w - 40), slot: { elements: [
    { kind: 'image', id: 'art', resourceId: 'cover', decorative: true,
      placement: { anchor: { to: 'bleed', edge: 'top-left' },
        size: { width: mm(TRIM.h), height: mm(TRIM.w) } } },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: ROUND, fontWeight: 700,
      fontSize: pt(60), lineHeight: 1, letterSpacing: pt(6), color: col('boat'),
      placement: at(22, 34) },
    { kind: 'text', id: 'latin', content: '{attr.latin}', fontFamily: ROUND, fontWeight: 700,
      fontSize: pt(9), lineHeight: 1.4, color: col('ink'), placement: at(22, 62) },
  ] } },
};

The cover is a page-wide heading design: the picture is anchored to the bleed with the page's own size (in the vertical flow its width runs down the sheet), and the title is set down the sky on the right in Zen Maru Gothic, 60 pt.

#4 · Load the paintings as bitmaps

script.js · lines 188–203in full code
// The scenes have the tier's shape, 612 : 280 (ART); the cover has the page's, 260 : 200.
const PICTURES = { // id: [file, width, height, alt text in the book's language]
  cover: ['cover-1430.jpg', 1430, 1100, 'あおい かわに あかい かみの ふねが うかんで いる。'],
  rain: ['rain-1400.jpg', 1400, 641, 'まどべの ちゃぶだいで、みいちゃんが あかい かみで ふねを おって いる。'],
  stream: ['stream-1400.jpg', 1400, 641, 'みいちゃんが おがわに ふねを ながし、てを ふって いる。'],
  frog: ['frog-1400.jpg', 1400, 641, 'かわの いしの うえの かえるが、ながれて いく ふねに はなしかけて いる。'],
  bridge: ['bridge-1400.jpg', 1400, 641, 'きの はしの したを ふねが くぐり、ちいさな さかなが ついて くる。'],
  heron: ['heron-1400.jpg', 1400, 641, 'ひろい かわの きしで、しろい さぎが ふねを みおくって いる。'],
  dusk: ['dusk-1400.jpg', 1400, 641, 'ももいろの ゆうやけの かわに ふねが うかび、とおくに うみが みえる。'],
  night: ['night-1400.jpg', 1400, 641, 'まんげつが かわに うつり、ひかりの みちの そばを ふねが すすむ。'],
  sea: ['sea-1400.jpg', 1400, 641, 'あおい うみに でた ふねの うえを、かもめが とんで いる。'],
  window: ['window-1400.jpg', 1400, 641, 'みいちゃんが まどから、まちの むこうの うみを みて いる。'],
};
const pictures = Object.entries(PICTURES).map(([id, [fileId, w, h, altText]]) => ({
  id, typeId: 'picture', kind: 'bitmap', createdAt: 0, updatedAt: 0, altText,
  placement: { span: 'side' }, bitmap: { fileId, format: 'jpeg', width: w, height: h } }));

The ten pictures are paintings, JPEG files in the recipe's assets/. The nine scenes are cut to the tier's shape, 612 : 280, and the cover to the page's, 260 : 200, so each fills its frame and nothing is cropped. Each is a bitmap resource declared at its pixel size, with alt text in the book's language, and its file is loaded under the resource's fileId before the build. Scenes 1,400 px wide print at about 165 dpi across the tier (resource types).

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 127 · A hiragana picture book, spaced by phrase ══════════
// https://postext.dev/en/cookbook/hiragana-picture-book
// Code: MIT · Story: written for the recipe (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Klee One, Zen Maru Gothic (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A picture book for small readers: hiragana only, a space between phrases, vertical.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} 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 editions
const RECIPE = 'hiragana-picture-book';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: the paper boat's red, river blues, a warm paper
const palette = {
  ink: '#2e2a26', // the text: a soft near-black
  boat: '#cf4430', // the boat, the title (4.6:1 on the paper)
  river: '#5d93ad',
  grass: '#86b665',
  muted: '#6e675f', // the colophon
  paper: '#fbf6ea',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  { id: 'main-color', name: 'boat (defaults)', value: { hex: palette.boat, model: 'hex' } },
];
// #endregion

const HAND = 'Klee One'; // 教科書体: the hand a child learns to write kana from
const ROUND = 'Zen Maru Gothic'; // the cover's title
const [BODY, LEAD] = [20, 36]; // pt: large kana, a line gap of 0.8 em
const PT = 25.4 / 72; // mm in a point
const TRIM = { w: 260, h: 200 }; // mm: a landscape picture book (横長)
const [CHARS, PICTURE, LINES] = [8, 14, 17]; // characters: text tier, picture tier; lines
const ART = { w: LINES * LEAD * PT, h: PICTURE * BODY * PT }; // mm: 215.9 × 98.8

// #region answer: わかち書き — a space between phrases, and lines that break only there
// The story is typed with an ordinary space (U+0020) after each phrase (文節). Japanese
// text may break between any two kana, so the space alone does not keep a phrase whole:
// keep-all drops the breaks between two letters and keeps those at a space, after 、。」
// and before 「. Kinsoku still applies.
const phrases = { wordBreak: 'keep-all' }; // cjk.wordBreak
const bodyText = {
  fontFamily: HAND, fontSize: pt(BODY), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  // Ragged: a justified line would stretch its spaces and its kana to fill the tier.

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

#Justify the lines

Justified, every line reaches the foot of the tier: the spaces between phrases stretch first, up to half an em, then the gaps between the kana (JLReq §3.8). A short line of 20 pt kana then shows wide gaps, which is why the recipe leaves its lines ragged.

-  textAlign: 'left', firstLineIndent: em(0),
+  textAlign: 'justify', firstLineIndent: em(0),

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 →

  • keep-all keeps the breaks the text already has: Postext does not find the phrases, so the author types the spaces. A phrase longer than the line still breaks inside, at the last place the kinsoku rules allow.
  • Chinese never spaces its words, and the Chinese primer A vertical reader with zhuyin to the right helps its young readers with readings instead; a Japanese picture book uses no kanji, so it needs no furigana, and the phrase spaces carry the reading.

Credits

Text
  • かみの ふね (The Paper Boat), a picture-book story in hiragana written for this recipe · Postext Cookbook · CC BY 4.0
Images
  • The cover: a red paper boat on a river through green meadows, a clear sky on the right for the title · Generated With Diffusion Models · original
  • Mii-chan folding the red paper boat at a low table by the window, after the rain · Generated With Diffusion Models · original
  • Mii-chan waving goodbye to the boat on the stream · Generated With Diffusion Models · original
  • A frog on a stone talking to the boat · Generated With Diffusion Models · original
  • The boat under a wooden footbridge, little fish following it · Generated With Diffusion Models · original
  • A white heron on the bank watching the boat on the wide river · Generated With Diffusion Models · original
  • Dusk: a pink sky over the river mouth and the sea beyond · Generated With Diffusion Models · original
  • Night: the full moon's reflection lighting the boat's way · Generated With Diffusion Models · original
  • The boat at sea, greeted by seagulls · Generated With Diffusion Models · original
  • Mii-chan at her window, looking towards the distant sea · Generated With Diffusion Models · original
Fonts
Klee One (SIL OFL 1.1) · Zen Maru Gothic (SIL OFL 1.1)
SandboxPDF