HTML Ruby Markup Extensions

1. Introduction

This section is non-normative

Ruby is a name for small annotations that are rendered alongside base text. This is especially useful for Japanese and other East Asian content (ruby may be called furigana in Japanese). It is most often used to provide a reading (pronunciation guide).

Ruby text is usually presented alongside the base text, using a smaller typeface. The name ruby originated from a named font size (about half the size of the normal 10 point font) used by British typesetters.

Typically ruby is used in East Asian scripts to provide phonetic transcriptions of obscure and little known characters, characters that the reader is not expected to be familiar with (such as children or foreigners learning to write), or characters that have multiple readings which can’t be determined by the context (eg. some Japanese names). For example it is widely used in educational materials and children’s texts. It is also occasionally used to convey information about the meaning of ideographic characters.

Specialized markup, as defined in this document, is necessary to describe the semantic associations between the base text and its annotations, to enable its various visual layouts as well as correct non-visual presentation and processing.

Note: CSS Ruby Annotation Layout Module Level 1 defines the ruby layout model in CSS, enabling the ruby presentation described above and frequently desired variations.

1.1. Background and Relation to the HTML Standard

A set of HTML elements to markup ruby has evolved over the years in multiple specifications, starting from the 2001 Ruby Annotation specification all the way to the current HTML Standard, with different incarnations varying in flexibility, complexity, or verbosity.

While concise and effective in simple cases, the ruby model described in the HTML Standard (at the time of writing this document) is insufficiently expressive to handle all use cases well. Moreover, some aspects of it are also not interoperably implemented; yet implementing them would not completely address the remaining use cases. Additionally, these aspects are at odds with the CSS layout model.

This specification is written to promote—​and guide implementations of—​an revised and extended model for ruby, in order to more completely address the needs of ruby on the Web platform. This effort is undertaken with the agreement of W3C and the WHATWG.

Appendix B: Comparison With The HTML Standard summarizes the main differences, and provides a brief overview of why these differences are desirable.

Note that the semantics of the subset of the HTML Standard that is interoperably implemented remain unchanged in this extension specification, making the ruby model described here backwards compatible with any ruby content supported by existing user agents.

It is hoped that the changes described here will in time be adopted by the WHATWG and integrated into the HTML Standard, reducing the delta between the two documents.

2. HTML Elements for Ruby

2.1. The ruby element

Categories:

Flow content.

Phrasing content.

Palpable content.

Contexts in which this element can be used:

Where phrasing content is expected.

Content model:

See prose.

Content attributes:

Global attributes

Accessibility considerations:

For authors.

For implementers.

DOM interface:

Uses HTMLElement.

The ruby element represents one or more ranges of phrasing content paired with associated ruby annotations. Ruby annotations are short runs of annotation text presented alongside base text. Although primarily used in East Asian typography as a guide for pronunciation, they can also be used for other associated information. Ruby is most commonly presented as interlinear annotations, although other presentations are also used. A more complete introduction to ruby and its rendering can be found in W3C’s What is ruby? article and in CSS Ruby Annotation Layout Module Level 1.

This example shows Japanese text, with ruby markup used to annotate the ideographs with their pronunciation.

<ruby>霧<rt>きり</rt></ruby>とも<ruby>霞<rt>かすみ</rt></ruby>とも

A typical rendering would be something akin to the following image:

The content model of ruby elements consists of one or more of the following ruby segment sequences:

1. One or more phrasing content nodes or rb elements (or a combination) representing the base-level content being annotated (the ruby base range).
2. One or more rt or rtc elements (or a combination) representing any annotations associated with the preceding base content, where each rtc element or sequence of rt elements represents one independent level of annotation (a ruby annotation range). Each annotation range, and annotation units within each range, and can optionally be preceded by / followed by / interleaved with individual rp elements. (The optional rp element can be used to add presentational content such as parentheses, which can be useful when rendering annotations inline, including as a fallback when ruby layout is not supported.)

Note: For authoring convenience, the internal ruby elements rb, rt, rtc, and rp have optional end tags.

In Taiwan, phonetic annotations for Chinese text are typically provided using Zhuyin characters (also known as Bopomofo). In mainland China, phonetic annotations are typically provided using Latin characters using Pinyin transcription. In this example, both are provided:

<ruby lang=zh-TW>
  <rb>美</rb><rtc><rt>ㄇㄟˇ</rt></rtc><rtc lang=zh-Latn><rt>měi</rt></rtc>
</ruby>

Certain features of HTML ruby allow for simpler markup:

• End tags can be omitted.
• Text contained directly by a ruby element implicitly represents a ruby base unit (as if it were contained in an rb element).
• Consecutive rt children of a ruby element are implicitly grouped into a ruby annotation range (as if they were contained in an rtc element).
• Text contained directly by an rtc element implicity represents a ruby annotation unit.

In effect, the above example is equivalent (in meaning, though not in the DOM it produces) to the following:

<ruby lang=zh-TW>
  美<rt>ㄇㄟˇ<rtc lang=zh-Latn>měi
</ruby>

Note: The CSS Ruby Annotation Layout Module Level 1 enables authors to control the rendering of the HTML ruby element and its contents, supporting a variety of layouts based on the same markup.

Three rendering styles are commonly used with Zhuyin (Bopomofo) characters. (Annotations here are shown in blue for clarity, though in actual uses there would be no color distinction.)

When the text is written vertically, the phonetic annotations are rendered to the right, along the base text:

In horizontal writing, they are frequently also typeset to the right, in this case sandwiched between individual base characters:

However, sometimes Zhuyin annotations are instead typeset above horizontal base text:

These differences are stylistic, not semantic, and therefore share the same markup:

<ruby lang=zh-TW>
  <rb>電<rb>腦
  <rt>ㄉㄧㄢˋ<rt>ㄋㄠˇ
</ruby>

2.1.1. Ruby Segmentation and Pairing

Within a ruby element, content is parcelled into a series of ruby segments. Ignoring inter-element whitespace and rp elements, each ruby segment consists of:

• One ruby base range: zero or more ruby base units, each of which is either a DOM range containing a single child rb element or a maximal DOM range of child content that does not contain a child rb element.
• Zero or more ruby annotation ranges, each a DOM range corresponding to either a single rtc element or to a maximal sequence of consecutive rt elements. The ruby annotation range is further parcelled into a sequence of ruby annotation units: if it consists of a sequence of rt elements, then each such element is an individual ruby annotation unit; if it consists of an rtc element, then each of its child rt elements and each maximal DOM range of non-rt child content is a ruby annotation unit.

Annotating text character by character is also typical in Chinese. In this example, each character is individually annotated in its own ruby element:

<ruby>千<rt>qiān</ruby><ruby>里<rt>lǐ</ruby><ruby>之<rt>zhī</ruby><ruby>行<rt>xíng</ruby>﹐<ruby>始<rt>shǐ</ruby><ruby>於<rt>yú</ruby><ruby>足<rt>zú</ruby><ruby>下<rt>xià</ruby>。

Multiple adjacent ruby segments can also be combined into the same ruby parent:

<ruby>千<rt>qiān</rt>里<rt>lǐ</rt>之<rt>zhī</rt>行<rt>xíng</ruby>﹐<ruby>始<rt>shǐ</rt>於<rt>yú</rt>足<rt>zú</rt>下<rt>xià</ruby>。

The process of annotation pairing associates ruby annotation units with ruby base units. Within each ruby segment, each ruby base unit is paired with a ruby annotation unit from each ruby annotation range. If a ruby annotation range consists of an rtc element that contains no rt elements, the single ruby annotation unit represented by its contents spans (is paired with) every ruby base unit in the ruby segment. Otherwise, each ruby annotation unit in the ruby annotation range is paired, in order, with the corresponding ruby base unit in the segment’s ruby base range. If there are not enough ruby base units, any remaining ruby annotation units are assumed to be associated with empty, hypothetical bases inserted at the end of the ruby base range. If there are not enough ruby annotation units in a ruby annotation range, the remaining ruby base units are assumed to not have an annotation from that annotation level.

<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し</ruby>

<ruby><rb>京<rb>都<rb>市<rp>（<rt>きょう<rt>と<rt>し<rp>）</ruby>

2.1.2. Markup Patterns for Multi-Character Ruby

This section is non-normative

In the simplest examples, each ruby base unit contains only a single character, a pattern often used for character-per-character phonetic annotations. However, ruby base units are not restricted to containing a single character. In some cases it may be impossible to map an annotation to the base characters individually, and the annotation may need to jointly apply to a group of characters.

For example, the Japanese word for “today” is written with the characters 今日, literally “this”+“day”. But it’s pronounced きょう (kyō), which can’t be broken down into a “this” part and a “day” part.

Therefore phonetic ruby indicating the reading of 今日 would be marked up as follows:

<ruby>今日<rt>きょう</ruby>

Ruby can also be used to describe the meaning of the base text, rather than (or in addition to) the pronunciation. In such cases, both the base text and the annotation are typically made of multiple characters, with no meaningful subdivision possible.

Here a compound ideographic word has an English-derived synonym (written in katakana) given as an annotation:

<ruby>境界面<rt>インターフェース</ruby>

Here a compound ideographic word has its English equivalent directly provided as an annotation:

<ruby lang="ja">編集者<rt lang="en">editor</ruby>

In compound words, although phonetic annotations might correspond to individual characters, they are sometimes nonetheless typeset to share space above the base text, rendering similar to annotations on multi-character bases. However, there are subtle distinctions in their rendering that require encoding the pairing relationships within the compound word as well as its identification as a word. Furthermore, sharing space in this way versus rendering each pair in its own visual “column” is a stylistic preference: the markup needs to provide enough information to allow for both renderings (as well as correct inlining).

In this example, we will use the Japanese noun “京都市”, meaning “Kyoto City”. Its characters are pronounced “きょう”, “と”, and “し”, respectively. (Distinct colors shown in these examples for clarity: in actual usage there would be no color distinction.)

Such compound words could be rendered with phonetic annotations placed over each character one by one. In this style, when an annotation is visually longer than the character it annotates, surrounding text is pushed apart, to make the correspondance between each character and its annotation clear.

However, it is common to present such a word with its annotations sharing space together when they would otherwise create a separation in the base text, to preserve the implication that it is a single word. This style is called “jukugo ruby” (“jukugo” meaning “compound word”).

Even when presenting as “jukugo ruby“ though, the annotation are not always merged. If a line break occurs in the middle of the word, the annotations are expected to remain associated with the correct base character.

Whether—and how much—the annotations are merged can vary, and can depend on the font size, as “jukugo ruby“ only merges annotations when at least one of them is longer than its base.

Since choosing to render as “jukugo ruby” or not is a stylistic choice, the same markup needs to enable both—​and it needs to encode both the pairing information within the word as well as the grouping of these pairs as a single word:

<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し</ruby>

Correct “jukugo ruby” is not be possible if all the base characters are part of a single rb element and all the annotation text in a single rt element, as their individual pairings would be lost.

Note: For more details on Japanese and Chinese ruby usage and rendering, see Requirements for Japanese Text Layout 日本語組版処理の要件(日本語版) (particularly Ruby and Emphasis Dots and Appendix F), Rules for Simple Placement of Japanese Ruby, and the section on Interlinear annotations of Requirements for Chinese Text Layout - 中文排版需求.

2.2. The rb element

Categories:

None.

Contexts in which this element can be used:

As a child of a ruby element.

Content model:

Phrasing content.

Content attributes:

Global attributes

DOM interface:

Uses HTMLElement.

An rb (“ruby base”) element that is the child of a ruby element represents a ruby base unit: a unitary component of base-level text annotated by any ruby annotation(s) to which it is paired.

An rb element that is not a child of a ruby element represents the same thing as its children.

<ruby>base<rt>annotation</ruby>

<ruby><rb>base<rt>annotation</ruby>

2.3. The rt element

Categories:

None.

Contexts in which this element can be used:

As a child of a ruby or of an rtc element.

Content model:

Phrasing content.

Content attributes:

Global attributes

Accessibility considerations:

For authors.

For implementers.

DOM interface:

Uses HTMLElement.

An rt (“ruby text”) element that is the child of a ruby element or of an rtc element that is itself the child of a ruby element represents a ruby annotation unit: a unitary annotation of the ruby base unit to which it is paired.

An rt element that is not a child of a ruby element nor of an rtc element that is itself the child of a ruby element represents the same thing as its children.

2.4. The rtc element

Categories:

None.

Contexts in which this element can be used:

As a child of a ruby element.

Content model:

Either phrasing content or a sequence of rt elements; optionally preceded, interleaved with, or followed by individual rp elements.

Content attributes:

Global attributes

DOM interface:

Uses HTMLElement.

An rtc (“ruby text container”) element that is the child of a ruby element represents one level of annotation (a ruby annotation range) for the preceding sequence of ruby base units (its ruby base range).

Note: In simple cases, rtc elements can be omitted as a ruby annotation range is implied by consecutive rt elements. However, they are necessary in order to associate multiple levels of annotation with a single ruby base range, for example to provide both phonetic and semantic information, phonetic information in different scripts, or semantic information in different languages.

In this example, the Japanese compound word 上手 ("skillful") has phonetic annotations in both kana and romaji phonetics while at the same time maintaining the pairing to bases and annotation grouping information.

This enabled by the following markup:

<ruby>
  <rb>上<rb>手
  <rt>じよう<rt>ず
  <rtc><rt>jou<rt>zu
</ruby>

Note: Text that is a direct child of the rtc element implicitly represents a ruby annotation unit as if it were contained in an rt element, except that this annotation spans all the bases in the segment.

In this example, the Chinese word for San Francisco (旧金山, i.e. “old gold mountain”) is annotated both using pinyin to give the pronunciation, and with the original English.

Which is marked up as follows:

<ruby>
  <rb>旧<rb>金<rb>山
  <rt>jiù<rt>jīn<rt>shān
  <rtc>San Francisco
</ruby>

Here, a single base run of three base characters is annotated with three pinyin ruby text segments in a first (implicit) container, and an rtc element is introduced in order to provide a second single ruby annotation being the city’s English name.

An rtc element that is not a child of a ruby element represents the same thing as its children.

2.5. The rp element

Categories:

None.

Contexts in which this element can be used:

As a child of a ruby or rtc element, either immediately before or immediately after an rtc element or a ruby annotation unit.

Content model:

Text.

Content attributes:

Global attributes

Accessibility considerations:

For authors.

For implementers.

DOM interface:

Uses HTMLElement.

The rp (“ruby parenthetical”) element represents nothing. It is used to provide presentational content (such as parentheses) around ruby annotation units, to be shown when presenting ruby content inline, without using ruby-specific layout. This may happen when using a user agent that does not support ruby layout, or for stylistic reasons. In typical ruby layout, it is not displayed.

...<ruby>漢<rb>字<rp>（<rt>かん<rt>じ<rp>）</ruby>...

...漢字（かんじ）...

<ruby>
  <rb>♥<rp>: <rt>Heart<rp>, <rtc lang=fr>Cœur</rtc><rp>.</rp>
  <rb>☘<rp>: <rt>Shamrock<rp>, <rtc lang=fr>Trèfle</rtc><rp>.</rp>
  <rb>✶<rp>: <rt>Star<rp>, <rtc lang=fr>Étoile</rtc><rp>.</rp>
</ruby>

♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.

3. Optional Tags

An rb element’s end tag may be omitted if the rb element is immediately followed by an rb, rt, rtc or rp element, or if there is no more content in the parent element.

An rt element’s end tag may be omitted if the rt element is immediately followed by an rb, rt, rtc or rp element, or if there is no more content in the parent element.

An rtc element’s end tag may be omitted if the rtc element is immediately followed by an rb or rtc element, or if there is no more content in the parent element.

An rp element’s end tag may be omitted if the rp element is immediately followed by an rb, rt, rtc or rp element, or if there is no more content in the parent element.

4. Rendering

The following rules are added to the HTML user agent style sheet:

ruby { display: ruby; }
rb { display: ruby-base; white-space: nowrap; }
rbc { display: ruby-base-container; } /* For compatibility with XHTML-inspired markup */
rp { display: none; }
rt { display: ruby-text; }
rtc { display: ruby-text-container; }
ruby, rb, rbc, rt, rtc { unicode-bidi: isolate; }
rtc, rt {
  font-variant-east-asian: ruby;
  text-emphasis: none;
  white-space: nowrap;
  line-height: 1;
}
rtc, :not(rtc) > rt {
  font-size: 50%;
}
rtc:lang(zh-TW), :not(rtc) > rt:lang(zh-TW) {
    font-size: 30%;
  }

5. Conforming Features

Appendix A: Editorial Tweaks to HTML

This section is non-normative

In complement to the normative statements made in the main body of this specification, this section details additional editorial changes that would be desirable to make to the HTML Standard in order to make it fully align it with what is covered here.

• Remove the outdated informative description of CSS annonymous box generation for ruby bases in the following paragraph in HTML § 15.3.4 Phrasing content:

  For the purposes of the CSS ruby model, runs of children of ruby elements that are not rt or rp elements are expected to be wrapped in anonymous boxes whose display property has the value ruby-base. [CSS-RUBY-1]

  The matter is already covered in exhaustive detail by CSS Ruby Annotation Layout 1 § 2.2 Anonymous Ruby Box Generation.

• Replace the following note in HTML § 15.3.4 Phrasing content:

  Note: When it becomes possible to do so, the preceding requirement will be updated to be expressed in terms of CSS ruby. (Currently, CSS ruby does not handle nested ruby elements or multiple sequential rt elements, which is how this semantic is expressed.)

  Note: In CSS, this is achieved by default: the initial value of the ruby-position property is alternate, which produces this effect.

• Replacing the ruby, rt, rp row of the table in HTML § 4.5.29 Usage summary, with the following:

  Element	Purpose	Example
  ruby, rb, rt, rtc, rp	Ruby annotations	<ruby><rb>旧<rb>金<rb>山<rp> (<rt>jiù<rt>jīn<rt>shān<rtc><rp>: </rp>San Francisco</rtc><rp>)</ruby>

• Updating the table at HTML §  Elements to add rows for rb and rtc, and to replace the rows for rp, rt, and ruby, as follows:

  Element	Description	Categories	Parents†	Children	Attributes	Interface
  rb	Ruby base	none	ruby	phrasing	globals	HTMLElement
  rp	Parenthesis for ruby annotation text	none	ruby; rtc	text	globals	HTMLElement
  rt	Ruby annotation text	none	ruby; rtc	phrasing	globals	HTMLElement
  rtc	Ruby annotation container	none	ruby	phrasing; rt; rp	globals	HTMLElement
  ruby	Ruby annotation(s)	flow; phrasing; palpable	phrasing	phrasing; rb; rt; rtc; rp*	globals	HTMLElement

• Updating the table at HTML §  Element interfaces to add the following two rows:

  Element(s)	Interface(s)
  rb	HTMLElement
  rtc	HTMLElement

  Appendix B: Comparison With The HTML Standard

  This section is non-normative

  Note: This comparison is based on the state of the HTML Standard at the time of writing this document. If the HTML Standard adopts some or all of the changes described here, or otherwise evolves its handling of ruby, this section is expected to be updated accordingly, but there could be a delay before this happens.

  While this specification reintroduces the previously obsoleted rb and rtc elements, it makes no changes to HTML § 13.2 Parsing HTML documents: these elements are handled there already, including their optional end tags.

  There are, however, differences in how the various ruby related elements can be used, the two essential ones being:

  1. In addition to the ability to interleave rt elements between anonymous ruby bases, the previously obsoleted rb element is restored, enabling the so-called tabular markup pattern where several consecutive bases are followed their respective annotations:

     <ruby>
       <rb>…<rb>…<rb>…
       <rt>…<rt>…<rt>…
     </ruby>
     

     Without rb and tabular markup, in order to have the individual base/annotation pairing necessary to correct handle the various possible presentations of ruby on compound words, interleaving the rt elements between segments of base text would be required. However, such this markup would not enable correct ruby inlining.

     Moreover, interleaved markup is also a source of issues with operations like copy&paste, searching through the document, or speech synthesis, due to the base text being interrupted by the annotations.

  2. This document defines a different model for handling multiple levels of annotations:
     • The ability to associate multiple consecutive rt elements with the preceding base text segment without using explicit annotation containers is dropped. This pattern does not have interoperable implementations with the semantics intended by the HTML Standard, and is in tension with tabular markup.

       Instead, the previously obsoleted rtc element is restored, providing the ability to indicate multiple annotation ranges over the same base(s), using either interleaved or tabular markup patterns.

     • While the ability to nest ruby is retained, specialized semantics for nested ruby are dropped. That markup pattern is strictly less expressive than using rtc for additional levels of annotations, since it does not allow pairing individual annotations in the outer ruby with individual bases in the inner ruby. The example about “上手” can therefore be realized using rtc but could not be with nested ruby.

       Nested ruby as defined in the HTML Standard also does not have interoperable implementations beyond the ordinary semantics of nesting, and is at odds with the layout model of CSS Ruby Annotation Layout Module Level 1.

  A 2011 blog post by fantasai explains in more details these requirements and resulting design choices.

  Appendix C: Acknowledgements

  This section is non-normative

  This document derives from several sources (which to some degree also derive from each other). We would like to thank the contributors to all these sources, notably:

  • The many editors and contributors of the HTML Standard

  • Robin Berjon, editor of the previous version of W3C HTML Ruby Markup Extensions

  • The editors and contributors of Ruby Annotation

  In addition, none of this would be possible without the expert input, many years of research, and extensive documentation by the participants of the Internationalization Working Group, notably:

  • The many contributors to Requirements for Japanese Text Layout 日本語組版処理の要件(日本語版)

  • The many contributors to Requirements for Chinese Text Layout - 中文排版需求

  • Richard Ishida

  • Elika J. Etemad (aka. fantasai)

  Appendix D: Changes

  This section is non-normative

  Changes since the 04 February 2014 W3C HTML Ruby Markup Extensions Working Group Note

  The markup model described here is substantially the same as the one established by the 2014 Working Group Note, though the text describing it, as well as the examples, has been extensively reworked.

  The parsing changes proposed in the 2014 Working Group Note are no longer discussed here as they have since been adopted by the HTML Standard.