Skip to main content

Displaying Furigana/Pinyin on a Website

Sometimes, when displaying East Asian/CJK characters on websites, there may be instances where we need to provide small annotations on the top of certain characters in order to show people how to pronounce them in a certain language, be it Hanyu Pinyin in Mandarin Chinese, Furigana in Japanese, or Jyutping in Cantonese, such as showing the readers how to pronounce our names that involve such characters properly.

The proper terminology for such little annotations is called 'ruby characters' (also known as 'ruby text' or simply 'ruby').

An example of ruby characters.

An example of ruby characters (image source).

How do we achieve this when we are building our own websites then?

The <ruby> element1​

Enter the <ruby> HTML element. By wrapping the characters, along with the annotations that we want to include on top of, within the <ruby> tag, we can add ruby text on webpages.

In raw HTML, the standard practice is to also include fallback open and close parantheses that are wrapped with <rp> tags and wrap the annotations with <rt> tags. The structure of the HTML code will then look like this...

<ruby>
人 <rp>(</rp><rt>nin</rt><rp>)</rp> 
間 <rp>(</rp><rt>gen</rt><rp>)</rp>
</ruby>

...whereas the CSS code may look something like this2.

ruby {
  font-size: 4em;
  ruby-align: center; /* Ruby text alignment */ 
}

Here is the result of the code above3.

人 (nin) 間 (gen)

Some more examples: my name in different languages​

That's basically it (for more platform-specific information, see footnote)! To further demonstrate its use cases, here are some examples showing how my Chinese name, 陳智恆 (written in Traditional Chinese characters), is pronounced in different languages.

Mandarin Chinese (Hanyu Pinyin)​

陳 (chén) 智 (zhì) 恆 (héng)

Mandarin Chinese (Bopomofo)​

陳 (ㄔㄣˊ) 智 (ㄓˋ) 恆 (ㄏㄥˊ)

Cantonese (Jyutping)​

陳 (can4) 智 (zi3) 恆 (hang4)

Hokkien (Peh-oe-ji)​

陳 (Tân) 智 (Tì) 恆 (Hîng)

Hakka (Phak-fa-su)4​

陳 (chhîn) 智 (chì) 恆 (hên)

Japanese (Katakana, in On'yomi)​

陳 (チン) 智 (チ) 恆 (コウ)
note

The corresponding romajis:-

  • チン: chin
  • チ: chi
  • コウ: kou

Bonus: my official English name​

Fun fact: my official English name is actually a transcription of the pronunciation of my Chinese name in Hokkien!

陳 (Tan) 智 (Tze) 恆 (Heng)

Further reading​

Footnotes​

  1. The naming convention of this HTML element has no relation to Ruby the programming language, which happens to have the same name, at all. ↩

  2. For more information on the ruby-align attribute, see here. ↩

  3. Although the above code snippets should work when working with raw HTML/CSS, to make this work in Docusaurus, some modifications on the HTML code need to be made in order to comply with the MDX format, which Docusaurus supports; see here for more information. In fact, the actual code behind the scene looks like this:

    <div style={{ textAlign: 'center', fontSize: '4em' }}>
    	<ruby style={{ rubyAlign: 'center' }}> 人 <rp>(</rp><rt>nin</rt><rp>)</rp> 間 <rp>(</rp><rt>gen</rt><rp>)</rp></ruby>
    </div>

    Luckily, things are less complicated in Hugo (which is another static site generator). It is possible to render raw HTML without modifications in websites generated by Hugo, provided that some markup settings are made beforehand in the site configuration file (see also here). ↩

  4. In Tai Poo (Dapu) accent; romanisation results obtained from Academia Sinica Min and Hakka Dictionary and Literature Corpus. The accents of Hakka, which can sound very different to each other, is another interesting topic worth looking into (see here, or here). ↩