Skip to content

The markdown-rubytext plugin for Grav allows you to add output <ruby> tag text in Markdown


Notifications You must be signed in to change notification settings


Repository files navigation

Grav Markdown RubyText Plugin

The markdown-rubytext plugin for Grav allows you to add output tagged text in Markdown:


This plugin is easy to install with GPM.

$ bin/gpm install markdown-rubytext


Simply copy the user/plugins/markdown-color/markdown-rubytext.yaml into user/config/plugins/markdown-rubytext.yaml and make your modifications.

enabled: true


simple and serial ruby

In your markdown file, thoses shortcodes:

This is {r}日(に)本(ほん)語(ご){/r}
and this is {r}漢(ㄏㄢˋ){/r}.

Will produce the following HTML:

This is <ruby>日<rp>(</rp><rt>に</rt><rp>)</rp>本<rp>(</rp><rt>ほん</rt><rp>)</rp>語<rp>(</rp><rt>ご</rt><rp>)</rp></ruby> 
and this is <ruby>漢<rp>(</rp><rt>ㄏㄢˋ</rt><rp>)</rp></ruby>.

Standart display:


new option (from v3.0.0): possiblity add a lang attributes

In your markdown file, it is now also possible to set lang attributes like:

This is {r=ja/ar}メダウルッシュ(مداوروش){/r},

this is {r=ja/fr}ピエル(Pierre)・()グリマル(GRIMAL){/r},

this is {r=ja/grc}トロイア(Τρωάς){/r},

this is {r}漢(ㄏㄢˋ){/r},

and this is {r=ja/ber}アマーズィーグ(ⴰⵎⴰⵣⵉⵖ){/r}族.

Will produce the following HTML, nested by a single ruby HTML tag:

This is <ruby lang="ja">メダウルッシュ<rp>(</rp><rt lang="ar">مداوروش</rt><rp>)</rp></ruby>, 

this is <ruby lang="ja">ピエル<rp>(</rp><rt lang="fr">Pierre</rt><rp>)</rp>・<rp>(</rp><rt lang="fr"></rt><rp>)</rp><rb>グリマル<rp>(</rp><rt lang="fr">GRIMAL</rt><rp>)</rp></ruby>,

this is <ruby lang="ja">トロイア<rp>(</rp><rt lang="grc">Τρωάς</rt><rp>)</rp></ruby>,

this is <ruby>漢<rp>(</rp><rt>ㄏㄢˋ</rt><rp>)</rp></ruby>,

and this is <ruby lang="ja">アマーズィーグ<rp>(</rp><rt lang="ber">ⴰⵎⴰⵣⵉⵖ</rt><rp>)</rp></ruby>.

Standart display:


to be valid HTML, lang attributes has to be part of:

  1. ISO 639-1 Language Codes List,


  1. ISO 639-2 Language Codes List

Important note:

To be valid, each lang attribute has to be of 2 or 3 letters maximum.

add possibility to enabled from page

In your config file:

enabled: true
active: false

In your markdown file:

    active: true

Would activate the plugin.

A example can be found with the shortcode-core plugin here.

GPM Installation (Preferred)

To install the plugin via the GPM, through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:

bin/gpm install markdown-rubytext

This will install the Markdown Rubytext plugin into your /user/plugins-directory within Grav. Its files can be found under /your/site/grav/user/plugins/markdown-rubytext.

Manual Installation

To install the plugin manually, download the zip-version of this repository and unzip it under /your/site/grav/user/plugins. Then rename the folder to markdown-rubytext. You can find these files on GitHub or via

You should now have all the plugin files under


NOTE: This plugin is a modular component for Grav which may require other plugins to operate, please see its blueprints.yaml-file on GitHub.

Admin Plugin

If you use the Admin Plugin, you can install the plugin directly by browsing the Plugins-menu and clicking on the Add button.


Before configuring this plugin, you should copy the user/plugins/markdown-rubytext/markdown-rubytext.yaml to user/config/plugins/markdown-rubytext.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true

Note that if you use the Admin Plugin, a file with your configuration named markdown-rubytext.yaml will be saved in the user/config/plugins/-folder once the configuration is saved in the Admin.