Proposal for Markdown ruby tag syntax

Spec
1 
Title    : Proposal for Markdown ruby tag syntax
Author   : Charles Jie (tw)
Email    : chjie7@gmail.com
Tags     : [markdown ruby syntax]
Revision : 0.2 - formalized by DeepSeek, then refined
Created  : 2025-05-09

Proposal for Markdown ruby tag syntax

requirements

  1. Easy to type – ASCII-only (avoid full-width （）【】).
  2. Easy to read – Base text remains clean (no quoting); ruby text should be subtle and ignorable.
  3. Minimal syntax – Prefer one symbol (e.g., ^) over pairs like [] or {}.
  4. Language-agnostic – No full-width symbols.
  5. Unambiguous – Visually scannable and machine-parsable.
  6. Intuitive design – ^ for <ruby> (implies “up” for ruby text); () for <rt> (enclosing a string/list).

proposed syntax

1. inline ruby

^base(ruby)        # e.g., ^振り向(ふりむ)く  
^base()            # Auto-fill ruby from a dictionary

2. outlined ruby block

standard (invisible by default):

^^^ruby[+]         # `ruby` is optional; add `+` to show this block as well (for learning)
  - ^base(ruby) - append extra text if needed (to explain etc.)
  - ^base(r1 r2)   # Multiple rubies (e.g., ^図書館(と しょ かん)  
^^^

alternative (render ruby literally by default):

^^^ruby[+][^]      # add `^` to render ruby objects  
  - base(ruby)     # Clean reference format  
  - base(r1 r2)  
^^^

Note: ^ acts as <ruby> without needing a closing tag (implied by )).

examples

  • ^振り向(ふりむ)く
  • ^振(ふ)り^向(む)く
  • ^図書館(としょかん)
  • ^図書館(と しょ かん)
  • ^台灣(ㄊㄞˊㄨㄢ)
  • ^香港(xiānggǎng)

comparison to existing conventions

  • じゅくご【熟語】→ Uses 【】 (visually heavy) for kanji.
  • しめ【締め・〆】→ ・ delimits multiple kanji.
1 Like