Ruby annotations

Render ruby (furigana) annotations with the caret syntax — {base}^{ruby} or base^{ruby}.

The ruby feature parses caret-syntax inline annotations and renders them as <ruby><rb>base</rb><rt>ruby</rt></ruby> HTML — the standard markup for phonetic annotations such as Japanese furigana.

Enable

// zfb.config.ts
export default defineConfig({
  markdown: {
    features: {
      ruby: true,
    },
  },
});

Primary syntax — caret

There are two caret forms:

Braced base

Wrap both sides in {…} with a ^ between them:

{これは}^{これ}

Renders as:

<ruby><rb>これは</rb><rt>これ</rt></ruby>

Any base text works — the non-ASCII rule (see below) does not apply to the braced form, so {ABC}^{xyz} is honored.

Bare base

Omit the braces around the base — the caret consumes the full preceding text run as the base:

これは^{これ}

Renders as:

<ruby><rb>これは</rb><rt>これ</rt></ruby>

Non-ASCII base required for the bare form. Because the bare form shares its AST shape with ASCII superscripts (2^{n}, x^{i}), the parser applies a false-positive guard: the base run must contain at least one non-ASCII character. CJK/kana bases are fine; ASCII-only bases are left untouched. For ASCII bases, use the braced form.

Multiple annotations in one paragraph are supported:

{日本語}^{にほんご}を{学ぶ}^{まなぶ}

<ruby><rb>日本語</rb><rt>にほんご</rt></ruby>を<ruby><rb>学ぶ</rb><rt>まなぶ</rt></ruby>

Legacy alias — pipe syntax

The pipe syntax from earlier versions is kept for backward compatibility:

{漢字|かんじ}を{学ぶ|まなぶ}

Renders as:

<ruby><rb>漢字</rb><rt>かんじ</rt></ruby>を<ruby><rb>学ぶ</rb><rt>まなぶ</rt></ruby>

Use the caret syntax for new content. The pipe form produces identical output and will remain supported, but it is no longer the primary syntax.

Edge cases

Caret-form edge cases (both forms treated analogously for the pipe form):

• {これは}^{これ} → <ruby> element

• 2^{n}, x^{i} (ASCII bare base) → left as literal text

• {base}^{} (empty annotation) → left as literal text

• ^{ruby} (no base) → left as literal text

Scope limitation — no auto-furigana

This feature only parses the explicit caret/pipe syntax. It does not automatically detect kanji and add furigana through morphological analysis (e.g. kuromoji-style segmentation). Automatic furigana assignment is a separate, much harder problem that is intentionally out of scope.

If you need auto-furigana, a separate dedicated feature would be required.