Add Furigana to an EPUB and Verify the Ruby Markup

Furigana work is not complete when readings have merely been entered in the manuscript. The exported XHTML should contain matching ruby and rt elements for every intended target. This sample used two chapters, six proper nouns, and four common terms. After ten readings were added individually, the generated XHTML contained ruby=10 and rt=10, and local structural validation returned valid: true. Visual rendering in vertical layout and external readers remains unverified.

Answer: Reconcile a reading ledger with the exported XHTML

Create a ledger containing the base text, reading, location, and processing result. If identical characters can have different readings in context, split the targets instead of applying an unrestricted replacement. After export, inspect the markup as well as the rendered page and confirm that ruby and rt occur as pairs.

This article is not a single-selection tutorial. STUDIO-158 demonstrates individual examples such as 東京 and 紫陽花. The present article treats a two-chapter inventory of ten terms and uses counts to detect omissions or unintended extra conversions before larger-scale production.

Sample: Six proper nouns and four common terms across two chapters

The article-specific starting ledger contained these ten pairs:

The expected structural result was ten ruby elements and ten rt elements. Separating proper nouns from common terms keeps work-specific readings distinct from ordinary vocabulary in the source ledger.

Procedure: Add each reading and verify the generated count

Use this application-independent sequence:

1. Search the manuscript and list every term that needs furigana.
2. Confirm each base-text and reading pair, then count the targets by chapter.
3. Add the furigana markup to the manuscript.
4. Export the EPUB.
5. Inspect the generated XHTML and count ruby and rt.
6. Run a structural check for missing resources and broken references.

The Stage 4 run added the ten pairs individually with the text ruby operation and completed export and inspection in 19 commands. A count of nine returns to the ledger and manuscript search. A count of eleven triggers a search for duplicate or overbroad replacement. Unequal ruby and rt counts return to the source notation and generated XHTML.

Measured result: Ten targets produced ten ruby and ten rt elements

The article-specific overall status was partial. The structural portion passed, but the visual image-based inspection was outside this run.

The measured values were ruby_count: 10, rt_count: 10, and valid: true. The EPUB had spine count 5, no images, no missing resources, and both nav and NCX documents with two items each. Their chapter targets were Text/p001.xhtml and Text/p002.xhtml.

The one-to-one count means that this generated XHTML did not reveal an omitted or extra ruby target in the ten-item sample. It does not automatically establish that every editorial reading is correct; the ledger above supplied the human-approved starting values.

A separate common regression sample used four chapters, vertical writing, and version 1.6. Its nine-command run produced spine count 8, one image, no missing resources, nav and NCX documents, and valid: true. That common result checks the vertical export path, not the ten-term ruby inventory.

Limits: Vertical rendering and external devices were not inspected

This run did not capture the vertical preview or visually test font-size reflow, external reading systems, KDP, or iPad rendering. Because the image-based stage was outside scope, matching counts cannot support a claim that furigana is positioned correctly on every screen.

Structural and visual checks have different recovery points. A count mismatch returns to the source notation. A visual collision despite matching counts returns to styling or target-range adjustment. KDP and iPad presentation remain unverified until those environments are actually inspected.

What Rune Studio covers

Rune Studio’s documented features include adding furigana to selected text, visually distinguishing its source notation, exporting EPUB 3, and previewing vertical writing. The CLI guide defines a text ruby operation with a source file, matched base text, and reading. Those are Stage 3 product capabilities.

The ten terms, two chapters, ruby=10, rt=10, spine count 5, zero missing resources, and valid: true are Stage 4 measurements. General EPUB requirements are available in W3C EPUB 3.3, and the product overview is on the Rune Studio website.

Conclusion: Pass the ten structural targets and keep rendering open

In the two-chapter sample, six proper nouns and four common terms produced ten ruby and ten rt elements. Local structural validation passed, and no referenced resource was missing.

Vertical presentation, font-size changes, external readers, KDP, and iPad remain unverified, so the overall result stays partial. Treat the reading ledger and structural count as one gate and visual legibility as a separate gate.