Proposal for Ruby (Furigana) Syntax in Markdown
date
Jun 27, 2025
slug
markdown-ruby
status
Published
tags
lang-eng
Design
summary
A proposal for adding Ruby (Furigana) to Markdown with syntax
[base]^^(annotation) or base^^(annotation). This intuitive format supports multi-level ruby, grouping, markdown integration, positioning control, and escaping. This paper also reviews previous proposals and includes W3C standards references.type
Post
Translation
This project is ongoing. A markdown-it plugin implementing this proposed syntax is under development. Extensions to other systems like Obsidian and Logseq are also planned.
TLDR;
Here I propose a new syntax extension for Markdown to support HTML's Ruby notation (also known as Phonetic Guides, Furigana, or Interlinear Texts).
The syntax is intuitive:
[base]^^(annotation), or simply base^^(annotation).For more details, here is a perfect introduction for you:
Examples
Design Rationale
Considerations
- Easily Parsed
- Compatibility with mainstream Markdown dialects, and use cases such as Pandoc and note-taking apps (Logseq, Obsidian etc)
- Typography considerations beyond CJK, including IPA phonetics, stroke order annotations, and potential CSS features
- Intuitive design that feels natural when handwriting and maintains familiarity for users
Review of the previous proposals
{漢字|かんじ}
Proposed by DenDenMarkdown, implemented https://github.com/lostandfound/markdown-it-ruby
Syntax not unfamiliar to standard markdown. Clustered, cannot be abbreviated. Coincides with pandoc attributes. Not working for mono ruby where base is half width. No multi-layer support.
[漢字]{かんじ}
Proposed by a StackExchange user, then re-implemented https://github.com/iltrof/furigana-markdown-it with unicode adaption
Intuitive, but curly brackets coincides with pandoc attributes
[漢字(かんじ)]
Proposed by JuanitoFatas, implemented https://lepture.com/en/2022/markdown-ruby-markup
Extends square brackets adding parsing difficulties, and text cluttered in plain reading. Messy when nested.
Examinations
.png?table=block&id=21ff4a91-c2b1-80f6-8d1c-c6f36975a83d&cache=v2)
.png?table=block&id=21ff4a91-c2b1-80f1-bc74-faa28244be10&cache=v2)
References
- W3C discussion: https://www.w3.org/community/itlcg/wiki/Use_Cases
- W3C standards https://www.w3.org/TR/css-ruby-1/
- Guide on ruby position: https://developer.mozilla.org/en-US/docs/Web/CSS/ruby-position
- CommonMark discussion: https://talk.commonmark.org/t/proper-ruby-text-rb-syntax-support-in-markdown/2279/18