Ruby

Created May 28, 2026Takeshi Takatsudo

Adds ruby annotation support for CJK text, rendering an inline caret syntax to native HTML ruby markup.

The ruby feature adds phonetic ruby annotations for CJK text, rendering an inline syntax to standard HTML <ruby> markup.

Requires zfb 0.1.0-next.14 or newer

The {base}^{ruby} syntax 500'd the SSR render at zfb 0.1.0-next.13 (#1815). It is fixed in zfb 0.1.0-next.14 (upstream Takazudo/zudo-front-builder#600) and is now enabled in zudo-doc's zfb.config.ts — the live example below is rendered by the running pipeline.

Configuration

Enable the feature with the ruby key. It accepts the true shorthand:

zfb.config.ts

export default defineConfig({
  markdown: {
    features: {
      ruby: true,
    },
  },
});

Syntax

The annotation uses a caret followed by the reading in braces, written immediately after the base text — {base}^{ruby}. The base is the run of characters directly preceding the caret:

日本語^{にほんご}

Live example

The source above, rendered by this page's pipeline:

日本語にほんご

HTML output

The annotation is rendered as semantic <ruby> markup:

<ruby><rb>日本語</rb><rt>にほんご</rt></ruby>

Scope

The feature parses only the explicit {base}^{ruby} syntax. It does not perform automatic kanji detection or morphological analysis to assign furigana — that is intentionally out of scope. The base is taken greedily from the contiguous characters before the caret, so separate the base from preceding text with a delimiter when you need a narrower annotation.

View source on GitHub