# Proposal for Markdown ruby tag syntax

**URL:** <https://talk.commonmark.org/t/proposal-for-markdown-ruby-tag-syntax/5018>\
**Category:** Spec\
**Created:** [May 11, 2025, 9:53pm UTC](https://talk.commonmark.org/t/proposal-for-markdown-ruby-tag-syntax/5018 "2025-05-11T21:53:18Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![chjie](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/c/c5a1d2/32.png) [@chjie](https://talk.commonmark.org/u/chjie)\
**Post date:** [May 11, 2025, 9:53pm UTC](https://talk.commonmark.org/t/proposal-for-markdown-ruby-tag-syntax/5018/1 "2025-05-11T21:53:18Z")

</div>

* * *

```
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

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

```

### 2. outlined ruby block

#### standard (invisible by default):

```auto
^^^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):

```auto
^^^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.

* * *

---

<div class="post-metadata">

**Author:** ![mathiassm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mathiassm/32/3434_2.png) [@mathiassm](https://talk.commonmark.org/u/mathiassm)\
**Post date:** [April 7, 2026, 7:22pm UTC](https://talk.commonmark.org/t/proposal-for-markdown-ruby-tag-syntax/5018/2 "2026-04-07T19:22:04Z")

</div>

I don’t know how content is usually conected here for reference, but, _for reference_ (both to the author here and future readers), see [Proper ruby text (\<rb\>) syntax support in Markdown](https://talk.commonmark.org/t/proper-ruby-text-rb-syntax-support-in-markdown/2279)