Using furigana/ruby with Markdown

First a little context! In many East Asian languages, a technique is used to make it easier to read characters that people might not recgonise. For example, the Japanse word for tea is pronounced “ocha”. It contains a kanji character and to help people learn, the phentic is written above it.


This is written in HTML like so:

    茶 <rp>(</rp><rt>ちゃ</rt><rp>)</rp>

You can also use it to write its ‘romanised’ pronounication, such as my name:

    マ <rp>(</rp><rt>ma</rt><rp>)</rp>
    ス <rp>(</rp><rt>su</rt><rp>)</rp>

There is no official way to do this in Markdown, as far as I know.

djfun/furigana_markdown, a Python Markdown extension, uses this:


Which becomes:


amclees/furigana-markdown, for Discourse, uses this:


So there isn’t an established way of doing it it seems, but it would be great to see if there was a way of having some sort of support for this.

1 Like

Do you happen to know how HTML editors use ruby in those languages? Is the formatting prescribed at a standard of a sort? :slight_smile:

I just tested this in a normal Japanese markdown page in Hugo, and it renders fine as is. I just pasted in the <ruby>茶<rp>(</rp><rt>ちゃ</rt><rp>)</rp><ruby> like a span, to test, and it works fine mixed in there. It did not appear to disrupt the markdown processing.

Edit: one thing that does not look good is, when you mix in a kanji character like this to English, the line height is effected and the page looks kind of messy. Adding ruby makes it worse. On an all-Japanese page, it’s probably not as much of a problem.

1 Like

No I don’t actually! Mozilla have a few references, but would be interesting to know what others do.

Yeah it has its downfalls when you’re making a page that’s in English, such as when you’re teaching Japanese – but I guess that’s fairly niche and can be negated. When I’ve used that, I tend to separate them in blocks rather that doing it in-line. If you’re teaching kanji on a Japanese page then I guess it’s probably more reasonable.

Good point that it works well with just the HTML! I think I’d just assumed it would be messy without even trying, but it’s not so bad looking at it.


1 Like

Well, if you’re making a page that needs rubii then I imagine you can format it how you need to, either way.


Some time ago I tried to implement that furigana extension in blackfriday, and today I made a pull request hoping it is useful to someone.