Purpose and content model
Ruby annotations place short explanatory text alongside base text, often to show pronunciation of East Asian characters. Ruby is the container. Rt supplies the annotation. Rp contains fallback punctuation for environments that do not render ruby layout, helping the text remain intelligible in a linear presentation.
These elements describe a specific relationship between base characters and annotations. They are not generic superscript controls or a convenient way to stack arbitrary text. For a multi-character term, decide whether the pronunciation belongs to the whole term or to individual characters; the markup should reflect that decision.
Syntax and working example
<p><ruby>漢<rp>(</rp><rt>かん</rt><rp>)</rp></ruby>字</p>Supported attributes and behavior
Ruby, rt, and rp use global attributes. Language metadata can identify the language of the base or annotation where necessary. CSS ruby-position and other ruby layout properties can influence presentation, but support and writing-mode behavior need testing. Rt and rp have constrained placement inside ruby rather than being ordinary standalone paragraphs.
Another practical pattern
<p><ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby> is a place name.</p>Accessibility and browser notes
Ruby speech output varies across browser and screen-reader combinations. Do not assume the annotation will always be announced exactly once in the desired order. Where pronunciation is essential to a task, provide an understandable plain-language explanation as well. Keep annotations large enough to read at normal zoom.
Common mistakes
Do not rely on obsolete rb or rtc markup for new examples. Do not use ruby to emulate a tooltip that should instead be a normal explanation. Parentheses belong in rp only when they serve as meaningful fallback rather than being part of the annotation itself.
Verify your implementation
Inspect horizontal and vertical writing modes if the product supports both. Zoom the text and test line wrapping around a ruby group. Read the fallback representation as ordinary text and verify that it still communicates which pronunciation belongs to which base text.
Standard status and sources
Standard; browser availability must be checked independently of specification status.