るりま(Ruby リファレンスマニュアル)のソースを Markdown に移行しました

2026年7月、るりま(Ruby の日本語リファレンスマニュアル)のドキュメントソースを、 長年使ってきた RD ベースの独自記法(RRD)から GitHub Flavored Markdown(GFM)ベースの記法に移行しました。 すでに本番切替も完了していて、いま docs.ruby-lang.org/ja/ で 見られるページは Markdown ソースからビルドされたものです。 この記事はその成果報告と、「これから編集したい人はどこを触ればいいの?」の案内です。

るりまとは

るりまは、Ruby の組み込みクラスから標準ライブラリ、 C API まで、すべてのリファレンスを日本語で提供しているプロジェクトです。 ドキュメント本体は rurema/doctree、 それを処理・公開するツールは rurema/bitclust という リポジトリで管理されています。

何が変わったのか

読む側にとっては、ほとんど何も変わりません。URL もページ構成もそのままです。 むしろ Markdown ネイティブの描画になったことで、インラインコードの <code> 表示や テーブルなど、旧記法では表現できなかったマークアップが反映されるようになり、 少し読みやすくなっています。

大きく変わったのは書く側です。ドキュメントのソースが、こういう独自記法から:

= class Array < Object
include Enumerable

== Instance Methods

--- each {|item| ... } -> self

各要素に対してブロックを評価します。

@raise TypeError 引数が正しくない場合に発生します。

#@samplecode 例
[1, 2, 3].each {|i| puts i }
#@end

こういう Markdown になりました:

---
library: _builtin
include:
  - Enumerable
---
# class Array < Object

## Instance Methods

### def each {|item| ... } -> self

各要素に対してブロックを評価します。

- **raise** `TypeError` -- 引数が正しくない場合に発生します。

```ruby title="例"
[1, 2, 3].each {|i| puts i }
```

ポイントをいくつか:

• 本文の大部分は標準的な GFM です。コードブロックは ```ruby、リストは -、 GitHub 上で .md を開けばそのままプレビューできます
• メソッド定義は ### def ... のように、見出しにキーワードを付けて表現します
• include などの構造データは YAML front matter に集約しました
• るりま独自のバージョン分岐(#@since 3.1 〜 #@end)はそのまま維持しています。 1つのソースから Ruby 3.0〜4.1 の各バージョン向けマニュアルをビルドする仕組みは 従来どおりです
• [m:Array#each] のようなクロスリファレンス記法だけは独自拡張として残っています
• モジュール関数の表記は、旧記法の Math.#atan2 から、RBS のモジュール関数定義 def self?.bar に似せた Math?.atan2 に変わりました。あわせて表示側も対応し、Ruby 4.0 以降の バージョンのページでは見出し・本文中のリンク・検索のすべてが ?. 表記に なっています(3.4 以前のページは従来どおり .# 表示のままです。検索は どちらの表記でもヒットします)

記法の詳細は仕様書 MARKUP_SPEC.md に、移行全体の背景や FAQ は markdown-announcement.md にまとまっています。ふだん GFM を書いている人向けには、 CommonMark・GFM と違うところだけ(独自拡張と、強調 **bold** など 非対応のまま静かに素通しされる記法)を1ページにまとめた MarkdownDialect.md があります。書き始める前にここだけ眺めておくとハマりにくいはずです。VS Code で編集する人向けのシンタックスハイライト定義も doctree の tools/vscode/rurema-markdown/ に用意しました。

読む側の改善もいろいろ

「読む側はほとんど変わらない」と書きましたが、移行と前後して読む側にも 改善が入っています。

• 以前からあったコード例のシンタックスハイライトと COPY ボタンまわりも整理し、 枠だけの出力例を含むすべてのコードブロックでコピーできるようになりました (後述の RUN ボタンの実行結果もコピーできます)
• Ruby 3.2 以降の各バージョンのページでは、コード例をその場で実行できる RUN ボタンが付きました。ruby.wasm を使って ブラウザの中だけで動くので、サーバーにコードが送られることはありません。 ページのバージョンに合った Ruby で動くのもポイントです
• サポートが終了した Ruby バージョンのページには、EOL であることを知らせる バナーが出るようになりました
• メソッドの見出しに、「Ruby 3.2 から」のような対応バージョンのバッジが 付きました。そのメソッドがどのバージョンから使えるのか(廃止されたものは どのバージョンまであったのか)が、バージョンを切り替えて見比べなくても その場で分かります
• 地の文中のインラインコードに背景色が付き、コードと本文を見分けやすくなりました
• ブラウザタブのタイトルに別名も表示されるようになりました。 たとえば Enumerable#collect のページのタイトルには map も並ぶので、 検索結果やタブの中から目当てのメソッドを見つけやすくなっています
• 各ページ上部の検索ボックスでは表示中のバージョン内を、 検索ページでは全バージョンを横断して検索できます。 さらに defined?・undef・alias のようなメソッドではない言語キーワードでも、 言語仕様の該当セクションに直接ジャンプできるようになりました

どれも小さな変化ですが、「リファレンスを読みながらちょっと試す」「うろ覚えの 名前から目的の説明にたどり着く」がページ内で完結するようになっています。

ドキュメントの中身も一斉整備しました

移行後の7月には、2014 年から積み上がっていた doctree の open issue 181 件を 全件棚卸しして、対応できるものをまとめて解消しました。現在残っているのは 方針検討中の数件だけです。

• 長年そのままだった説明の誤りを、すべて現在の Ruby で実測したうえで修正しました。 例: LocalJumpError の発生条件の説明、Module#name が確定するタイミング、 Rational('1/3.1') の挙動、Numeric#fdiv に Complex を渡したときの挙動など
• サンプルコードの書き方(リテラル優先、例外になる行の注釈書式 # ~> など)を 執筆ガイドラインとして明文化し、既存のコード例にも適用を始めています。 コード例は原則として実行して出力を確認したものになっています

「リファレンスの記述が手元の挙動と違う」と思ったら、それはたいてい直しどきです。 issue でも PR でも、報告はいつでも歓迎です。

どうやって移行したのか

「手作業で書き直した」わけではありません。RRD → Markdown の変換器と、 検証用の逆方向(Markdown → RRD)変換器を実装し、全 1250 ファイル (API リファレンス 1166・文書 68・C API 16)を機械的に一括変換しました。

移行で一番こわいのは「変換のどこかで内容が欠ける」ことなので、検証は段階を重ねています:

• ラウンドトリップ検証: 変換した Markdown を RRD に逆変換して元とバイト単位で比較。 全 1250 ファイルで 100% 一致
• データベース検証: 旧ソースと Markdown ソースそれぞれからマニュアル全体の データベースを構築して全エントリを比較(メソッド 9281・文書 66・C 関数 814、すべて一致)
• HTML 検証: 静的 HTML 全 13,535 ページを新旧経路で生成して突き合わせ。 差分は GFM 化による意図した改善だけ

そのうえで bitclust 本体が Markdown を直接パース・描画するようになり、 変換レイヤーはビルド経路から外れました。移行のための一時的な仕組みが 本番に残っていない、というのも今回こだわったところです。

ドキュメントを編集したくなったら

ここが実務上いちばん大事な変更点です。編集場所が変わりました。

• 編集するのは rurema/doctree の manual/ 配下の .md ファイル(manual/{api,doc,capi}/**/*.md)です
• いちばん簡単な入り口は公開ページ下部の編集リンクで、そのページの .md ファイルの GitHub 編集画面に直接飛べます。誤字修正ならブラウザだけで完結します
• 旧 refm/ ツリーはリポジトリにまだ残っていますが凍結中で、 編集しても公開サイトには反映されません(移行期間の後に削除予定です)

手順の詳細は doctree の CONTRIBUTING.md にあります。「Markdown なら書ける」という方はぜひ。誤字1文字の修正から歓迎です。

なお、以前から貢献してくれている方向けに補足すると、doctree の GitHub wiki にあった プロジェクト文書(執筆ガイドや FAQ など)は、リポジトリ内の docs/ ディレクトリに引っ越しました。 wiki は今後閉じる予定なので、ブックマークは docs/ の方に張り替えてください。

おまけ: 旧バージョンの検索も復活しました

移行作業と並行して、検索ページも サーバーサイド検索からクライアントサイドの静的検索に置き換えました。 このとき、長らく検索できなかった Ruby 1.8.7〜2.7.0 の旧バージョンのマニュアルも アーカイブから復元して検索対象に追加しています。現行の 3.0〜4.1 と合わせて、 1つの検索ボックスから全バージョンを横断検索できます。 古い Ruby をメンテナンスしている方はどうぞ。

なお、復元した旧バージョンのページは凍結扱いで内容の更新は行いませんが、 リンク先がスパムサイト化してしまった外部リンクの削除など、読者に実害のある 問題だけは個別に対応しています。

今後の予定

• 移行期間の後、凍結中の旧 refm/ ツリーを削除
• Markdown 対応版 bitclust gem のリリース(refe2 などローカルツール向け)
• メソッド定義の RBS 形式での記述対応の検討 (rurema/bitclust#250)

謝辞

今回の移行(変換器の実装、検証、bitclust のネイティブ対応、本番切替まで)は、 勤務先の株式会社Ruby開発が契約してくれている Claude Max(Claude Fable 5)を 使って進めました。独自記法のパーサと格闘しながら 1250 ファイルの等価性を 検証し切るような作業がここまで短期間で完了したのは間違いなくこのおかげです。 業務ツールを OSS 活動にも使わせてくれている会社に感謝します。

るりまは「Ruby で分からないことがあったら最初に見る場所」であり続けたいプロジェクトです。 Markdown になって書きやすくなった今、ドキュメントの改善にぜひ参加してみてください。