Ruby Annotations (ruby, rt, rp)

Technical Deep Dive & Specifications

WHATWG HTML Living Standard Specification

According to the official WHATWG specification:

• <ruby>: Represents content with ruby annotations (small runs of text alongside base text, typically used in East Asian typography to indicate pronunciation or provide annotations).
• <rt>: Marks the ruby text component of a ruby annotation.
• <rp>: Provides parentheses or other fallback delimiters around ruby text components for user agents that do not support ruby formatting.

Element Structure and Nesting Patterns

There are two primary patterns for structuring Ruby annotations:

Pattern A: Character-by-Character (Mono-Ruby)

Each individual base character is paired immediately with its specific phonetic reading:

<ruby>
  漢<rp>(</rp><rt>かん</rt><rp>)</rp>
  字<rp>(</rp><rt>じ</rt><rp>)</rp>
</ruby>

Pattern B: Whole-Word (Group Ruby)

A multi-character word is paired with a combined phonetic reading:

<ruby>
  東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp>
</ruby>

                                  +---------------------------+
                                  |     <ruby> CONTAINER      |
                                  +---------------------------+
                                                |
               +--------------------------------+--------------------------------+
               |                                |                                |
               v                                v                                v
       [ BASE TEXT ]                    [ <rp> FALLBACK ]                [ <rt> RUBY TEXT ]
   Ideograms / Kanji / Hanzi         Parentheses hidden in ruby          Phonetic pronunciation
   e.g., "漢"                        e.g., "(" and ")"                   e.g., "かん"

The <rp> Fallback Mechanics

How does <rp> (Ruby Parentheses) work?

1. In Modern Browsers (Chrome, Firefox, Safari, Edge): The browser engine understands <ruby> and positions <rt> above the base text. It automatically applies display: none to all <rp> elements so parentheses are hidden.
2. In Legacy Parsers / Text-to-Speech Readers: The parser ignores <ruby> and renders inline text: 漢(かん)字(じ), ensuring the phonetic reading is never lost!

Advanced CSS Ruby Controls

You can control ruby text position and alignment using modern CSS:

ruby {
  ruby-position: over; /* 'over' (default above), 'under' (below), 'inter-character' */
  ruby-align: center;   /* 'center', 'start', 'space-between', 'space-around' */
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 8: line-height: 2.2; — Generous line height prevents overlapping when ruby annotations appear on multiple lines of text.
• Line 46: <ruby>新<rp>(</rp><rt>しん</rt><rp>)</rp>幹... — Mono-ruby structure pairing each kanji with its hiragana reading.
• Line 57: <ruby>北<rp>(</rp><rt>běi</rt><rp>)</rp>京<rp>(</rp><rt>jīng</rt><rp>)</rp></ruby> — Chinese Hanzi with pinyin tone marks over vowels (běi jīng).
• Line 46 & 57: <rp>(</rp> and <rp>)</rp> — Fallback parentheses that render in text-only terminals while remaining invisible in modern browsers.

Expected Browser Render Output

• The Japanese sentence displays 新幹線 with しんかんせん neatly aligned above the respective characters.
• The Chinese sentence displays 北京 with běi jīng centered above each Hanzi.
• In text-mode browsers or when copied to the clipboard, the text copies cleanly with fallback parentheses: 新(しん)幹(かん)線(せん).