remark-ruby-novel

A remark plugin that converts novel-style ruby syntax into HTML <ruby> elements.

Motivation

In Japanese and Chinese web novels, authors commonly annotate characters with phonetic readings using a simple inline syntax:

漢字《かんじ》

This plugin transforms that syntax into proper HTML ruby markup, making it easy to add furigana (Japanese reading aids) or phonetic annotations to your markdown content.

Installation

npm install remark-ruby-novel

bun add remark-ruby-novel

pnpm add remark-ruby-novel

Usage

import { remark } from 'remark'
import remarkHtml from 'remark-html'
import remarkRubyNovel from 'remark-ruby-novel'

const markdown = '彼女《かのじょ》は東京《とうきょう》に住んでいる。'

const result = await remark()
	.use(remarkRubyNovel)
	.use(remarkHtml, { sanitize: false })
	.process(markdown)

console.log(String(result))

Syntax

The plugin recognizes Han characters followed by annotations in double angle brackets:

| Input | Output | | -------------------- | ---------------------------------------------------------- | | 漢字《かんじ》 | <ruby>漢字<rp>(</rp><rt>かんじ</rt><rp>)</rp></ruby> | | 東京《とうきょう》 | <ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby> |

The <rp> elements provide fallback parentheses for browsers that don't support ruby.

Options

All options are optional and default to the behavior shown in Syntax.

| Option | Type | Default | Description | | --------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------- | | leftBracket | string | 《 | Opening delimiter for the ruby annotation. | | rightBracket | string | 》 | Closing delimiter for the ruby annotation. | | optionalIsolateMain | boolean | false | When true, also recognize an explicitly delimited main text (via the brackets below), not just Han runs. | | mainLeftBracket | string | 『 | Opening delimiter for the isolated main text (used only when optionalIsolateMain is true). | | mainRightBracket | string | 』 | Closing delimiter for the isolated main text (used only when optionalIsolateMain is true). |

Custom ruby delimiters

remark().use(remarkRubyNovel, { leftBracket: '〈', rightBracket: '〉' })
// 漢字〈かんじ〉 → <ruby>漢字<rt>かんじ</rt></ruby>

Optional isolated main text

When optionalIsolateMain is enabled, the base text can be any content wrapped in 『』 (configurable), so non-Kanji text can be annotated. The implicit Han-run syntax still works alongside it.

remark().use(remarkRubyNovel, { optionalIsolateMain: true })
// 『hello』《world》 → <ruby>hello<rt>world</rt></ruby>
// 漢字《かんじ》     → <ruby>漢字<rt>かんじ</rt></ruby>  (still works)

License

MIT