Markdown Extension: Ruby Markup

This blog renders markdown by HTML::Pipeline that uses the Ruby library of CommonMark¹: CommonMarker, which is GitHub’s fork of the reference parser for CommonMark.

CommonMark spec does not have specifications for Ruby Markup. For CommonMarker and the majority of the internet, you write the Ruby markup HTML directly in your markdown document:

<ruby>漢字<rt>かんじ</rt></ruby>

However, I was blogging many Japanese posts which I would need to write a lot of HTML. It would be much nicer to have something easy to write the ruby markup.

Finding solutions

I found this thread on CommonMark forum. They are discussing adding ruby syntax support in Markdown but they haven’t concluded yet. So I build my own. This is what I ended up using on this site:

[漢字(かんじ)]

This generates:

<ruby>
漢字<rp>(</rp><rt>かんじ</rt><rp>)</rp>
</ruby>

Which looks like:

漢字(かんじ)

Why?

This works great for me because:

• It looks like Markdown

• It does not need to type any special brackets 【】

• It works when you want to add links

  [漢字(かんじ)](https://jisho.org/search/漢字)
  

  漢字かんじ

• You can annotate each Kanji separately:

  [漢(かん)][字(じ)]
  

  漢(かん)字(じ)

• They can link separately:

  [漢(かん)](https://jisho.org/search/漢)[字(じ)](https://jisho.org/search/字)
  

  漢かん字じ

• Or link together:

  [[漢(かん)][字(じ)]](https://jisho.org/search/漢字)
  

  漢(かん)字(じ)

It is open sourced at JuanitoFatas/html-pipeline-ruby_markup. Let me know if you have any feedback!