Material for MkDocs を日本語対応した話＆初めてのOSSコントリビュート

結論: MkDocs (0.17以上) + Material (2.0.3以上) テーマにおいて、次の設定を行うことで日本語UI表示＋日本語検索(マルチバイト検索)が可能になります！

theme:
  name: 'material'
  language: 'ja'
extra:
  search:
    language: 'jp'

MkDocs いいよ、MkDocs

www.mkdocs.org

最近仕事で MkDocs というドキュメントジェネレーターを導入し始めています。マニュアルやドキュメントを作る際、オフライン(スタンドアロン環境)で参照したり他部門に成果物を共有したりする場合があるため Wiki や CMS はポータビリティの関係からできれば使いたくないし、かといってHTML手書きはさすがに辛い。また PowerPoint や Word で消耗したくもない。そんなとき思いついたのが静的ファイルを生成してくれるドキュメントジェネレーターでした。

Sphinx や Re:VIEW などが有名ですがそこまでの表現力・柔軟性は要りませんし、何より他のシステムとの互換性から Markdown を使いたかったので一番よく耳にする MkDocs を採用しました。（Python製ってのも惹かれた）

f:id:miyahan:20171115000825p:plain

一般的な Markdown ファイルにサイト構成(ページ一覧)を書いたYAMLファイルを１つ作るだけで動き、吐き出されるHTMLもおシャレでわかりやすくかなり気に入ったのですが、唯一、日本語検索ができないという制約が引っかかりました。

Material for MkDocs 日本語対応

MkDocsによるドキュメント作成 - Qiita のように独自に改良されている事例もありましたが、ドキュメントをビルドするたびにファイルを差し替える必要があり面倒そうでした。そんなときサードパーティー製のテーマである Material for MkDocs で言語を指定するとマルチ言語対応の全文検索ライブラリ lunr-languages を自動でロードすることに気づきました。どうやら独自で多言語化対応を進めているようです。

まだ日本語には対応しておらず日本語を指定するとエラーになって使えない状態でしたが、見よう見まねで言語定義ファイルを作ってみたところ日本語表示＆日本語検索が動くようになりました！

f:id:miyahan:20171107004355p:plain f:id:miyahan:20171107004404p:plain

やればできるもんですね。

日本語検索ができない事に困っている記事をよく見かけましたし、なによりも自分が解決されてほしいと思っていたので勇気を出して日本語対応のプルリクを送ろうと決意しました。

はじめてのOSSコントリビュート

とはいえプルリクなんて送ったこともないですし、そもそも git もろくに使えず、手に負えなくなったらプロジェクトごと作り直すなんてことをやってるくらいです。でも幸いコントリビュートの方法がドキュメントに詳しく書いてあったのでその通り行動しました。

プロジェクトを fork して separate git branch でいじれとな。セパレート？？ブランチを切れってことかな？で、プルリクを送る前に yarn でビルドしろとな。ビルドしたファイルが必要？ビルドが通ることをチェックする目的？？他の人のプルリクみるとビルドファイルは push してないのでたぶん後者だ。

ひーひー言いながらなんとかプルリクを送信。

f:id:miyahan:20171107001251p:plain

おお、なんか自動でコードの品質チェックとビルドが走ってる〜。これが噂に聞く異世界の超科学、継続的インテグレーション！！そして数分後、

f:id:miyahan:20171107001952p:plain

通ったーー!! ヽ(ﾟ∀ﾟ)ノ
手の平にこんなに汗をかいたのは久しぶりです。

そしてさらに翌日…

f:id:miyahan:20171107002302p:plain

ｷﾀ━━━( ´∀`)・ω・) ﾟДﾟ)・∀・)￣ー￣)´_ゝ`)━━━!!!!

f:id:miyahan:20171107002547p:plain

泣きそう。

そして同日、僕のコミットを取り込んだバージョンが晴れてリリースされました。お仕事が早い。英単語をいくつか和訳しただけではありますが、こうして人生初めてのOSSコントリビュートは無事成功したのでした。

オチ

プルリクのコメント欄で作者とやりとりしたところ、実は実装は済んでおり以前から設定ひとつで日本語検索を有効化できることが判明。しかし公式ドキュメントの表記が間違っており、自分も含めて誰も使えていない状況だったというオチでした。まあこのやりとりのおかげでドキュメントのミスに気づいて修正できたし、UIが日本語で表示されるというのは紛れもなく機能追加だからよしとしましょう。

Previous が 前 になっただけで何がうれしいんだ？と思う方も多いと思いますが、義務教育で習う英単語１つにすら拒絶反応を起こす英語アレルギー持ちの人（というかただの思考停止してる人）がいるため、日本語化はけっこう重要なんです。

Material for MkDocs 日本語対応方法

というわけで最後に日本語表示＆日本語検索するための設定方法を紹介します。mkdocs.yml を次のように設定するだけです。

theme:
  name: 'material'
  language: 'ja'
extra:
  search:
    language: 'jp'

じつはここに罠がありまして、日本語の言語コードは ISO 639-1 で ja と決められていますが、lunr-languages はそれを誤って jp で実装してしまっているためいろいろ不都合が生じていました。その対処として上記の通り2種類の言語設定を書く必要があります。

なおこの問題は master ブランチではすでに修正が入っており、次のリリース(lunr-languages 2.0.0?)で ja にリネームされ、jp は ja へのエイリアスになる予定です。そうなれば、extra/search/language の設定は不要になります。

というわけで、MkDocs + Material は日本語フルサポートとなりました。みなさんぜひ活用なさってください！！