• Home
• コーポレートブログ
• ドキュメント生成ツール「MkDocs」でRedmine Guide日本語訳のWebサイトを作ってみた

前田です。私のことをRedmineのことばかりやっている人と認識している人がいるかもしれませんが、そんなことはありません。実は8年前に「入門Radiant CMS」というRubyベースのオープンソースのCMSの本を書いたこともあります。

ということで、今回の話題はRedmineではなく、先日Webサイトの制作に使ったツール「MkDocs」です。

「MkDocs」はMarkdownで書かれたファイルをもとにWeb公開用のドキュメントを生成するツールです。8月下旬、MkDocsを利用して、これまで「Redmine.JP」というWebサイト内で公開していた「Redmine Guide 日本語訳」という文書を単独のWebサイト http://guide.redmine.jp/ での公開に切り替えました。

Redmine Guideとは

「Redmine Guide」は、オープンソースのプロジェクト管理ツール「Redmine」のドキュメントです。公式サイトのWiki上で利用者が協力し合って更新しています。

その日本語訳である「Redmine Guide 日本語訳」は、私が2008年頃から私が少しずつ翻訳して公開してきました。以前は Redmine.JP というWebサイトのコンテンツの一部でしたが、2017年8月20日からはRedmine.JPから切り出して独立したWebサイト http://guide.redmine.jp/ での公開に切り替えました。

Redmine Guide 日本語訳で改善したかったこと

これまでRedmine.JPの一部として公開していたコンテンツを独立したサイトにわざわざ移行したのは、何年も改善したいと思っていたことがいくつかあったためです。

改善したかったこと①：もっと見やすくしたかった

Webサイトの作りの問題でもありますが、ドキュメント全体を見通せる目次がRedmine Guide日本語訳のトップにしかない、ページ間の遷移のリンクが不十分などの問題がありました。

もちろんそれなりの手間をかけて作り込めば解決できる問題ですが、これまで作り込むための時間を確保できず、ずっと問題を解決できずにいました。

改善したかったこと②：ソースコードを公開したかった

Webサイトで日本語訳を公開するだけでなく、誰もが自由に再利用しやすい形でソースコードを公開したいと何年も前から考えていました。例えばMarkdown形式のテキストをGitHubで公開するなどです。

元々が公式サイトのWikiで公開されているオープンな文書ですので、日本語訳についてはソースコードが公開されておらずHTMLのみが参照できるという状態は違和感がありました。また、公開しておけば、何かアイデアをお持ちの方にうまく活用していただいたり、翻訳に協力したいという方が現れたときに参加してもらいやすくなるというメリットもあります。

ただ、Redmine.JPの一部である限りは、Redmine.JP全体をまるごと公開する必要があったり、Redmine Guide 日本語訳の部分だけを切り出して再利用しにくいなどの問題があります。公開するためにはなんらかの整理が必要でした。

改善したかったこと③：更新作業を効率化したかった

Redmine.JPのWebサイトは400以上のページがあり、nanocでサイト全体のHTMLを生成するのに20秒程度かかっていました。ページを更新しているときに現時点の更新内容を確認しようと思うと20秒程度かけてコンパイルする必要があるため、もう少し更新を軽快に行えればと考えていました。

ドキュメント生成ツールMkDocs

Redmine Guide 日本語訳には改善したい点がいくつかありながらも何年間も手をつけることができずにいたのですが、ある日Twitterのタイムラインで MkDocs というツールが紹介されているのを見かけたことで、一気に前に進みました。

公式サイトを見ると "Project documentation with Markdown." とあり、目次があるような、ある程度の分量のドキュメントを作成することを目的としたツールのようです。

気になって詳しく調べてみると、なかなかよさそうなツールであることがわかりました。

• Markdownで記述したファイル群からWebサイトを生成できる
• 目次やナビゲーション（前ページ、次ページ、上の階層への移動など）が自動で生成される
• ソースコードが自動でハイライトされる
• あらかじめ複数のテーマが用意されていて、切り替えて利用できる
• 特にデザインを行わなくても用意されているテーマでそれなりに見れるサイトができる
• テーマのカスタマイズもそれほど難しくない
• mkdocs serve を実行すればWebサーバが起動し、Markdownのファイルを更新すると自動でHTMLが再生成される。また、Webブラウザも自動でリロードされる

機能を調べているうちに、ずっと気になっていたRedmine Guide日本語訳のリニューアルに利用することを思いつきました。MkDocsを知ったすぐ後の土日を使って移行作業をすることにしました。

nanocからMkDocsへの移行作業

MkDocsはシンプルなツールで、Markdownのテキスト群と、目次と設定の管理をする mkdocs.yml というファイルを書けばそれなりに使えます。Redmine Guide日本語訳の移行作業では、もっとも時間がかかったのはコンテンツをMkDocsが扱えるMarkdown形式に変換することです。

Redmine Guide日本語訳のソースコードはTextile形式で記述されていたため、まずはテキストフォーマットの変換ツール「pandoc」に通しました。

pandoc -f textile -t markdown_github RedmineInstall.textile > RedmineInstall.md

その後、mkdocs serve を実行してWebブラウザで表示を確認しながら、うまく変換できなかった箇所を1つ1つ手修正しました。

目視チェックと手作業での修正が結構手間だったのと、作業途中で訳文で気になった箇所の修正もしたので思った以上に時間がかかりました。土曜日の午後に作業を始めたのですが、43個のファイルの移行が完了し http://guide.redmine.jp/ を公開できたのは日曜日の夕方でした。

MkDocsに移行してよかったこと

8月20日から、Redmine Guide日本語訳をRedmine.JPから切り出してMkDocsでの管理に移行し、 http://guide.redmine.jp/ として公開しました。MkDocsに移行した結果、問題点として認識していたことを改善することができました。

ナビゲーションが充実して見やすくなった

サイドバーにドキュメント全体の目次兼ナビゲーションが表示され、周辺のページへの移動がしやすくなりました。また、ドキュメント全体の中での現在の位置もわかります。

ページ冒頭にはページ内の目次も表示され、最後まで目を通さなくてもそこに何が書いてあるのか把握するのが容易です。

スマートフォンにも対応できた

MkDocsで使用したテーマ「ReadTheDocs」はレスポンシブレイアウトに対応しています。これにより、Redmine Guide日本語訳でスマートフォン向けの画面も提供できるようになりました。

ソースコードを公開できた

これはMkDocsの直接のメリットではありませんが、Redmine.JPから切り出して単独のサイトして整理したことで、GitHubでの公開が実現できました。ライセンスはクリエイティブコモンズ（CC BY-SA 4.0）です。

https://github.com/farend/redmine-guide-ja

ほぼリアルタイムに更新結果をプレビューできるので更新作業が楽になった

mkdocs serve を実行するとWebサーバが起動し、Webブラウザでアクセスして表示を確認できます。Markdownのファイルを更新するとすぐにHTMLが更新されて、さらにブラウザで勝手にリロードが行われるので、感覚としては自動でブラウザの表示が変わります。ビルドやリロードを自分でやらなくてよいので、執筆に集中しやすくなりました。

移行前、nanocで管理されたWebサイト「Redmine.JP」の一部だったころは、ビルドやリロードのコマンドを頻繁にコマンドラインから実行していました。

Python Markdownが強力

MkDocsはPythonで書かれていて、MarkdownパーサーとしてはPython Markdownというライブラリを使っています。Python Markdownは便利な拡張が数多く含まれていて、MkDocsからは mkdocs.yml 内の markdown_extensions: に拡張の名前を追加することで簡単に利用できます。

Redmine Guide日本語訳では特に以下の拡張が役立ちました。

Admonition

https://pythonhosted.org/Markdown/extensions/admonition.html

注意事項や警告を目立つスタイルで表示させることができます。例えば、

!!! warning "重要"
    設定変更後は必ずアプリケーションを再起動してください。

と書くと以下のように表示されます。

Attribute Lists

https://pythonhosted.org/Markdown/extensions/attr_list.html

生成されるHTMLの要素に任意の属性を追加できます。例えば、見出しに対してid属性を指定したいときは次のように書くと、

### カスタムクエリ {: #Custom-queries }

以下のようなHTMLが生成されます。

<h3 id="Custom-queries">カスタムクエリ</h3>

Table of Contents

https://pythonhosted.org/Markdown/extensions/toc.html

Markdownのファイル内の任意の場所に [TOC] と書くと、ページ内の見出しを拾って生成した目次が挿入されます。

MkDocsの困っているところ

良いところばかり書きましたが、1つ困っているのが、組み込みの検索機能が日本語に対応していないことです。Redmine Guide日本語訳のサイトでは、検索ボックスをGoogleカスタム検索に置き換えて対処しました。

まとめ

MkDocsはシンプルながら強力なドキュメント生成ツールで、Markdown形式のファイル群を元にHTMLを生成します。手間をかけずに小ぎれいなWebサイトを作れるので、Web版のマニュアルなどを作るのにもってこいです。

MkDocsを知った2日後に思い立ってRedmine Guide日本語訳のサイトの移行に着手しましたが、難しい点はほとんどなく簡単に新しいサイトを作ることができました。