rehype-ruby-annotator 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 yukidoke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# rehype-ruby-annotator
+
+`rehype-ruby-annotator` は、HTML AST 内のテキストに `<ruby>` 要素を追加する rehype プラグインです。
+本文中の日本語に、あらかじめ定義したふりがなを自動で付与する用途を想定しています。
+
+```html
+<p>私は日本語を読む。</p>
+```
+
+```html
+<p>私は<ruby>日本語<rp>(</rp><rt>にほんご</rt><rp>)</rp></ruby>を読む。</p>
+```
+
+## 特徴
+
+- 登録した語句に一致したテキストへ `<ruby>` / `<rt>` / `<rp>` を挿入します。
+- 重複する候補がある場合は、左から最長一致で処理します。
+- `code`、`pre`、見出し、既存の `ruby` など、注釈を付けたくない要素を既定でスキップします。
+- ひとつの語句の一部だけにルビを付ける指定もできます。
+- `Intl.Segmenter` を使い、絵文字などの grapheme cluster も壊さず扱います。
+
+## インストール
+
+```sh
+pnpm add rehype-ruby-annotator
+```
+
+```sh
+npm install rehype-ruby-annotator
+```
+
+```sh
+yarn add rehype-ruby-annotator
+```
+
+## 動作環境
+
+- Node.js 18 以降を推奨します。
+- 実行環境で `Intl.Segmenter` が利用できる必要があります。
+- 古い Node.js やブラウザで使う場合は、事前に `Intl.Segmenter` の対応状況を確認してください。
+
+## 基本的な使い方
+
+以下は Markdown を HTML に変換する unified pipeline の最小例です。
+
+```ts
+import rehypeRuby from "rehype-ruby-annotator";
+import rehypeStringify from "rehype-stringify";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+
+const options = {
+    entries: [
+        {
+            segments: [
+                { base: "日本語", reading: "にほんご" },
+            ],
+        },
+        {
+            segments: [
+                { base: "東京駅", reading: "とうきょうえき" },
+            ],
+        },
+    ],
+};
+
+const file = await unified()
+    .use(remarkParse)
+    .use(remarkRehype)
+    .use(rehypeRuby, options)
+    .use(rehypeStringify)
+    .process("私は日本語を読む。");
+
+console.log(String(file));
+```
+
+`segments` に指定した `base` が本文に見つかると、対応する `reading` が `<rt>` として挿入されます。
+
+## Astro で使う例
+
+`astro.config.mjs` の Markdown 設定に追加します。
+
+```js
+import { defineConfig } from "astro/config";
+import rehypeRuby from "rehype-ruby-annotator";
+
+export default defineConfig({
+    markdown: {
+        rehypePlugins: [
+            [
+                rehypeRuby,
+                {
+                    entries: [
+                        {
+                            segments: [
+                                { base: "日本語", reading: "にほんご" },
+                            ],
+                        },
+                        {
+                            segments: [
+                                { base: "東京駅", reading: "とうきょうえき" },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        ],
+    },
+});
+```
+
+## エントリ形式
+
+### 語句全体にルビを付ける
+
+```ts
+{
+    segments: [
+        { base: "銀河鉄道", reading: "ぎんがてつどう" },
+    ],
+}
+```
+
+本文の `銀河鉄道` が、次のような要素に変換されます。
+
+```html
+<ruby>銀河鉄道<rp>(</rp><rt>ぎんがてつどう</rt><rp>)</rp></ruby>
+```
+
+### 語句の一部だけにルビを付ける
+
+`segments` には文字列も混ぜられます。文字列部分は一致には含まれますが、ルビは付きません。
+
+```ts
+{
+    segments: [
+        "銀",
+        { base: "河", reading: "が" },
+        "鉄道",
+    ],
+}
+```
+
+この場合、本文の `銀河鉄道` に一致し、`河` の部分だけが `<ruby>` になります。
+
+```html
+銀<ruby>河<rp>(</rp><rt>が</rt><rp>)</rp></ruby>鉄道
+```
+
+### `match` で一致文字列を明示する
+
+通常、照合に使う文字列は `segments` から自動で組み立てられます。
+意図しない指定ミスを検出したい場合は `match` を書けます。
+
+```ts
+{
+    match: "日本語",
+    segments: [
+        { base: "日本語", reading: "にほんご" },
+    ],
+}
+```
+
+`match` と `segments` から推測される文字列が一致しない場合はエラーになります。
+
+## オプション
+
+```ts
+import type { RehypeRubyOptions } from "rehype-ruby-annotator";
+
+const options: RehypeRubyOptions = {
+    entries: [],
+};
+```
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | --- | --- |
+| `entries` | `RubyEntryInput[]` | なし | ルビを付ける語句の一覧です。必須です。 |
+| `additionalSkipTags` | `string[]` | `[]` | 既定のスキップ対象に追加するタグ名です。 |
+| `skipTags` | `string[]` | `DEFAULT_SKIP_TAGS` | スキップ対象のタグ一覧を置き換えます。指定すると既定値は使われません。 |
+| `verbose` | `boolean` | `false` | `true` のとき、初期化と変換結果のログを出します。 |
+| `logger` | `RubyLogger \| false` | `console` | `verbose: true` のログ出力先です。`false` なら出力しません。 |
+
+## 既定でスキップされるタグ
+
+次のタグの中にあるテキストには、既定ではルビを付けません。
+
+```txt
+a, h1, h2, h3, h4, h5, h6,
+code, pre, kbd, samp,
+script, style, textarea,
+ruby, rt, rp,
+math, svg
+```
+
+既定のリストに追加する場合は `additionalSkipTags` を使います。
+
+```ts
+{
+    entries,
+    additionalSkipTags: ["span"],
+}
+```
+
+既定のリストを使わず、完全に置き換えたい場合は `skipTags` を使います。
+
+```ts
+{
+    entries,
+    skipTags: ["span"],
+}
+```
+
+## 一致ルール
+
+- テキストノードごとに処理します。HTML 要素をまたいだ語句には一致しません。
+- 同じ位置で複数の候補が一致する場合は、より長い語句を優先します。
+- 同じ `match` を持つエントリを複数登録するとエラーになります。
+- 空文字列に一致するエントリは登録できません。
+
+## 補助 API
+
+```ts
+import {
+    DEFAULT_SKIP_TAGS,
+    getEntryText,
+    normalizeEntry,
+} from "rehype-ruby-annotator";
+```
+
+| API | 説明 |
+| --- | --- |
+| `DEFAULT_SKIP_TAGS` | 既定のスキップ対象タグ一覧です。 |
+| `getEntryText(segments)` | `segments` から照合用テキストを組み立てます。 |
+| `normalizeEntry(entry)` | `RubyEntryInput` を検証し、照合用の形式に正規化します。 |
+
+## 開発
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```
+
+`pnpm test` は TypeScript のビルド後に `node --test` を実行します。
+
+## ライセンス
+
+MIT

package/dist/defaults.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_SKIP_TAGS: readonly string[];
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.js

@@ -0,0 +1,22 @@
+export const DEFAULT_SKIP_TAGS = [
+    "a",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "code",
+    "pre",
+    "kbd",
+    "samp",
+    "script",
+    "style",
+    "textarea",
+    "ruby",
+    "rt",
+    "rp",
+    "math",
+    "svg",
+];
+//# sourceMappingURL=defaults.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { default } from "./transform.js";
+export { DEFAULT_SKIP_TAGS } from "./defaults.js";
+export { getEntryText, normalizeEntry, } from "./normalize.js";
+export type { RubySegment, RubyEntrySegment, RubyEntryInput, NormalizedRubyEntry, RehypeRubyOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { default } from "./transform.js";
+export { DEFAULT_SKIP_TAGS } from "./defaults.js";
+export { getEntryText, normalizeEntry, } from "./normalize.js";
+//# sourceMappingURL=index.js.map

package/dist/normalize.d.ts

@@ -0,0 +1,4 @@
+import type { NormalizedRubyEntry, RubyEntryInput, RubyEntrySegment } from "./types.js";
+export declare function getEntryText(segments: RubyEntrySegment[]): string;
+export declare function normalizeEntry(entry: RubyEntryInput): NormalizedRubyEntry;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.js

@@ -0,0 +1,16 @@
+export function getEntryText(segments) {
+    return segments
+        .map((segment) => typeof segment === "string" ? segment : segment.base)
+        .join("");
+}
+export function normalizeEntry(entry) {
+    const inferredMatch = getEntryText(entry.segments);
+    if (entry.match !== undefined && entry.match !== inferredMatch) {
+        throw new Error(`Ruby entry match mismatch: match="${entry.match}", segments="${inferredMatch}"`);
+    }
+    return {
+        match: inferredMatch,
+        segments: entry.segments,
+    };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/transform.d.ts

@@ -0,0 +1,5 @@
+import type { Root } from 'hast';
+import type { VFile } from 'vfile';
+import type { RehypeRubyOptions } from "./types.js";
+export default function rehypeRuby(options: RehypeRubyOptions): (tree: Root, file: VFile) => void;
+//# sourceMappingURL=transform.d.ts.map

package/dist/transform.js

@@ -0,0 +1,101 @@
+import { DEFAULT_SKIP_TAGS } from './defaults.js';
+import { Trie } from './trie.js';
+import { normalizeEntry } from './normalize.js';
+import { visitParents } from 'unist-util-visit-parents';
+function rubyNode(segment) {
+    return {
+        type: "element",
+        tagName: "ruby",
+        properties: {},
+        children: [
+            { type: "text", value: segment.base },
+            {
+                type: "element",
+                tagName: "rp",
+                properties: {},
+                children: [
+                    { type: "text", value: "(" }
+                ]
+            },
+            {
+                type: "element",
+                tagName: "rt",
+                properties: {},
+                children: [
+                    { type: "text", value: segment.reading }
+                ]
+            },
+            {
+                type: "element",
+                tagName: "rp",
+                properties: {},
+                children: [
+                    { type: "text", value: ")" }
+                ]
+            }
+        ]
+    };
+}
+function textNode(text) {
+    return {
+        type: "text",
+        value: text,
+    };
+}
+export default function rehypeRuby(options) {
+    const logger = options.verbose === true && options.logger !== false
+        ? options.logger ?? console
+        : undefined;
+    logger?.info("[rehype-ruby] Annotator initialize start.");
+    const skipTags = new Set((options.skipTags ?? DEFAULT_SKIP_TAGS).map((tag) => tag.toLowerCase()));
+    for (const tag of options.additionalSkipTags ?? []) {
+        skipTags.add(tag.toLowerCase());
+    }
+    const trie = new Trie();
+    for (const entry of options.entries) {
+        trie.addData(normalizeEntry(entry));
+    }
+    logger?.info("[rehype-ruby] Annotator initialized.");
+    return (tree, file) => {
+        const startTime = performance.now();
+        let rubyCount = 0;
+        visitParents(tree, "text", (node, ancestors) => {
+            if (ancestors.some((n) => {
+                return n.type === "element" && skipTags.has(n.tagName);
+            })) {
+                return;
+            }
+            const nre = trie.searchAll(node.value);
+            if (!nre.segments.some((seg) => typeof seg !== "string")) {
+                return;
+            }
+            const parent = ancestors.at(-1);
+            if (!parent) {
+                return;
+            }
+            const index = parent.children.indexOf(node);
+            const newNodes = [];
+            let textBuffer = "";
+            for (const seg of nre.segments) {
+                if (typeof seg === "string") {
+                    textBuffer += seg;
+                }
+                else {
+                    if (textBuffer !== "") {
+                        newNodes.push(textNode(textBuffer));
+                        textBuffer = "";
+                    }
+                    newNodes.push(rubyNode(seg));
+                    rubyCount++;
+                }
+            }
+            if (textBuffer !== "") {
+                newNodes.push(textNode(textBuffer));
+            }
+            parent.children.splice(index, 1, ...newNodes);
+        });
+        const durationMs = performance.now() - startTime;
+        logger?.debug(`[rehype-ruby] ${file.path || "(unknown)"}: ${rubyCount} words, ${durationMs.toFixed(3)} ms.`);
+    };
+}
+//# sourceMappingURL=transform.js.map

package/dist/trie.d.ts

@@ -0,0 +1,15 @@
+import type { NormalizedRubyEntry } from "./types.js";
+interface TrieNode {
+    data: NormalizedRubyEntry | null;
+    child?: Map<string, TrieNode>;
+}
+export declare class Trie {
+    root: TrieNode;
+    segmenter: Intl.Segmenter;
+    constructor();
+    addData(data: NormalizedRubyEntry): void;
+    private search;
+    searchAll(text: string): NormalizedRubyEntry;
+}
+export {};
+//# sourceMappingURL=trie.d.ts.map

package/dist/trie.js

@@ -0,0 +1,95 @@
+function appendSegment(segments, segment) {
+    if (typeof segment === "string") {
+        const last = segments.at(-1);
+        if (typeof last === "string") {
+            segments[segments.length - 1] = last + segment;
+            return;
+        }
+    }
+    segments.push(segment);
+}
+export class Trie {
+    root;
+    segmenter;
+    constructor() {
+        this.root = {
+            data: null,
+        };
+        this.segmenter = new Intl.Segmenter("ja", { granularity: "grapheme" });
+    }
+    addData(data) {
+        if (data.match.length === 0) {
+            throw new Error("Empty match is not allowed.");
+        }
+        let current = this.root;
+        const segments = this.segmenter.segment(data.match);
+        for (const c of segments) {
+            current.child ??= new Map();
+            let nextNode = current.child.get(c.segment);
+            if (nextNode === undefined) {
+                nextNode = {
+                    data: null,
+                };
+                current.child.set(c.segment, nextNode);
+            }
+            current = nextNode;
+        }
+        if (current.data !== null) {
+            throw new Error(`${data.match} already exists.`);
+        }
+        else {
+            current.data = data;
+        }
+    }
+    search(segments, index) {
+        let current = this.root;
+        let result = null;
+        let matchedEnd = 0;
+        for (let i = index; i < segments.length; i++) {
+            if (!current.child) {
+                break;
+            }
+            const seg = segments[i];
+            if (!seg)
+                break;
+            const nextNode = current.child.get(seg.segment);
+            if (nextNode === undefined) {
+                break;
+            }
+            if (nextNode.data !== null) {
+                result = nextNode.data;
+                matchedEnd = i;
+            }
+            current = nextNode;
+        }
+        return result === null ? [null, 0] : [result, matchedEnd + 1 - index];
+    }
+    searchAll(text) {
+        const segments = [...this.segmenter.segment(text)];
+        const result = {
+            match: "",
+            segments: [],
+        };
+        let i = 0;
+        while (i < segments.length) {
+            const [res, len] = this.search(segments, i);
+            if (res === null) {
+                const seg = segments[i];
+                if (!seg)
+                    break;
+                result.match += seg.segment;
+                appendSegment(result.segments, seg.segment);
+                i++;
+            }
+            else {
+                result.match += res.match;
+                for (const s of res.segments) {
+                    appendSegment(result.segments, s);
+                }
+                i += len;
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=trie.js.map

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export interface RubySegment {
+    base: string;
+    reading: string;
+}
+export type RubyEntrySegment = RubySegment | string;
+export interface RubyEntryInput {
+    /**
+     * Optional assertion that must match the text inferred from segments.
+     */
+    match?: string;
+    segments: RubyEntrySegment[];
+}
+export interface NormalizedRubyEntry {
+    match: string;
+    segments: RubyEntrySegment[];
+}
+export interface RubyLogger {
+    info(message?: unknown, ...optionalParams: unknown[]): void;
+    debug(message?: unknown, ...optionalParams: unknown[]): void;
+}
+export interface RehypeRubyOptions {
+    entries: RubyEntryInput[];
+    additionalSkipTags?: string[];
+    skipTags?: string[];
+    logger?: RubyLogger | false;
+    verbose?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "rehype-ruby-annotator",
+  "version": "1.0.0",
+  "description": "A rehype plugin that adds HTML ruby annotations using user-provided entries.",
+  "keywords": [
+    "astro",
+    "rehype",
+    "ruby",
+    "furigana",
+    "japanese",
+    "annotation",
+    "unified",
+    "hast"
+  ],
+  "homepage": "https://github.com/yukidoke/rehype-ruby-annotator#readme",
+  "bugs": {
+    "url": "https://github.com/yukidoke/rehype-ruby-annotator/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yukidoke/rehype-ruby-annotator.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "yukidoke",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@types/hast": "^3.0.4",
+    "unist-util-visit-parents": "^6.0.2",
+    "vfile": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "pnpm run build && node --test test/rehype-ruby-annotator.test.mjs"
+  }
+}