Ruby annotations

Description.

Ruby annotations are small text written next to or above the main text. They are mainly used in CJK languages to indicate, for example, pronunciation.

⟵ Annotation.

⟵ Main text.

Nevertheless, in the examples that follow, we used Ruby notation with texts in French. It is unusual, no doubt, but this will allow the reader not to be distracted by the glyphs of Asian characters.

Ruby and HTML5.

HTML5 includes all the necessary tags to render the Ruby presentation:

ruby:

Container Ruby.

rb:

Delimit the base text. This tag can even be omitted.

rt:

Limits the annotation.

rp:

Character marking the beginning and/or end of the annotation text. Useful only for browsers that do not recognize Ruby notation.

rbc ✗:

Defines a container for multiple base texts.
Obsolete. Only the rb tag is still included in the standard.

rtc ✗:

Defines a container that can hold multiple annotation texts.
Obsolete. You should now use the rt tag in all cases.

First example. This is the simplest case: only the ruby, rb, and rt tags are used to delimit the container, the main text, and the annotation text.
It is even possible not to specify the rb tag, as all text included within a ruby element is by default considered main text. However, this simplification is not recommended, as it would then be more difficult to apply CSS styles to the main text.


	‹ruby›
	   ‹rb›TEXT‹/rb›
	   ‹rt›Annotation‹/rt›
	‹/ruby›

TEXTAnnotation

The rp tag can be added. It will be ignored by browsers that handle Ruby notation, but on browsers that do not support Ruby, it allows a character to be introduced at the beginning and end of the annotation.


	‹ruby›
	   ‹rb›TEXT‹/rb›
	   ‹rp›(‹/rp›
	   ‹rt›Annotation‹/rt›
	   ‹rp›)‹/rp›
	‹/ruby›

TEXTAnnotation

On a compatible browser

TEXT (Annotation)

On a browser that does
not recognize Ruby notation

Ruby and CSS.

The usual CSS properties can of course be used to style Ruby annotations, as seen in the example below.


	‹ruby›
		‹rb›TEXT‹/rb›
		‹rt›Annotation‹/rt›
	‹/ruby›

TEXTAnnotation

But there are properties specific to Ruby annotations:

ruby-align :

Defines text alignment in ruby syntax.

ruby-merge :

Describes how ruby annotations should be aligned when multiple annotations follow each other on the same line.

ruby-overhang :

Handles annotation overflow in a ruby presentation.

ruby-position :

Defines the position of the ruby annotation relative to the base.

The `display` property.

The display property allows you to set any element as a Ruby container or an element in a Ruby structure. However, if the document is HTML, it is preferable to use the predefined HTML tags (see above).

display:ruby;

Defines an element as a Ruby container.

display:ruby-base;

Defines an element as the main text of a Ruby structure.

display:ruby-text;

Defines an element as the annotation text of a Ruby structure.

display:ruby-base-container;

✗ Defines an element as a container for several main texts in a Ruby structure.

display:ruby-text-container;

✗ Defines an element as a container for multiple annotation texts in a Ruby structure.

Browsers compatibility with `ruby`.

As of now (2025), Ruby annotations and the various CSS properties that allow you to style them are only partially supported by browsers. Refer to the individual properties for more details.

Column 1

General support for ruby annotations and related properties.