MkDocsでマテリアルデザインなMarkdownドキュメントサイトを作ろう
MkDocsとは
MkDocs とは、 Markdown をもとにドキュメントサイトを構築する 静的サイトジェネレーターです。 Material for MkDocs とは、 MkDocs のテーマの１つであり、 Google が提唱しているマテリアルデザインを反映したものです。 このテーマが実によくできているので、じわじわと流行ってきているように感じます。
特徴
- Markdownファイルを放り込めば大体OK！
- テーマいろいろ
- モバイルサイズにも対応
- 静的サイトに載せられる（アプリサーバ不要）
記事コンテンツの全文検索ができる！
静的サイトなのに検索ができることに驚きです。ちょっとだけ仕組みを覗き見たところ、 生成コマンド実行時にインデックスらしきファイルを作っていました。 JavaScriptでゴリゴリやっている感じがするので、ちょっと重いかも。
他のテーマ
拡張Markdownの表現力
ドキュメントサイトではこういった注釈の表現はあると映えますよね。 このあたりできるのであれば、他の難しいドキュメント記法の仕組みにしなくてもよいという判断に揺らぎそうです。
実際に動かしてみよう！
手軽に素早く構築できるように、スターターキットを用意しました。 すぐにどんなものか試せるように、ありモノをちょちょいとやるだけで雰囲気がつかめます。
その導入手順を説明した記事も書いたので、気になった方はどうぞ。 Windows と Mac それぞれに場合分けして案内しているので、取り組みやすいと思います。 もしわからないことがあったら気軽に聞いてくれてイイヨ Tweet to @syonxv
実例とソースコード
以前からずっと書き溜めてきたMarkdownメモの寄せ集めサイトを刷新しました。
ソースコードはGitHubで公開しています。
キャプチャをご覧の通り、早速マテリアルデザインを逸脱しています（笑）。
これは設定で extra_css を指定することで拡張CSSを適用しています。
その他、ちょっと調整したいときにとても助かる仕組みですね。実際のソースを参考にしてみて下さい。
技術的な補足情報
Webサーバに載せることが前提
MkDocsで生成した静的サイト用ファイルは、ローカルでindex.htmlを開く使い方は想定されていません。
開くことと表示することはできますが、リンクから他の記事に遷移することができません。
これはMarkdownファイルへのリンクが ./TheTitle/ のように張られており、ファイルプロトコル上では
これが ./TheTitle/index.html と解釈されず、正しく表示できません。
他にも
ドキュメントサイトジェネレーターという観点では、 Read the Docs というオープンソースのサービスを 利用しているサイトもよく見かけます。まだしっかりと検証したことはありませんが、検討の候補としてチェックしておくとよいでしょう。
