2015-04-30

※2016/4/6 記事更新

こちらです。

Complete List | Hugo Themes にも Pull Request を送って、入れてもらっています。

Motivation

以前に Markdown によるドキュメント管理について、記事を書きました。

Markdown による中規模ドキュメンテーションシステムについて調べた。 - weblog of key_amb

その後、Pelican や MkDocs を試したものの、なんだか帯に短しタスキに長しな感じで、必要十分なドキュメンテーション用の機能を満たすものがない感じでした。

Pelican 触ってみたところ、やはりデフォルトはブログ用ですね。ドキュメンテーションに適したレイアウトにするには Hugo などと同様、初期工数が要りそう。
— きいあむ → @progrhyme (@key_amb) 2015年4月4日

だったら MkDocs だ、とこちらも触ってみたところ、むしろ小規模向けって感じがしてきました。Markdownの拡張記法も少なく、ドキュメントが多くなっていく(10頁以上〜)とつらいかもしれません。でも小規模だったらシンプルで使いやすいと思います。
— きいあむ → @progrhyme (@key_amb) 2015年4月4日

「ないなら作ればよい」というわけで、ドキュメント用に自分がほしい機能が入ったテンプレートを作ることにしました。

Markdown ベースの静的サイトジェネレータはいろいろありますが、今だと Hugo がなういようなので、Hugo のテーマを作ることにしました。

…で、出来たものが Bootie Docs になります。
デモサイトに、このテーマそのもののドキュメントを書きました。

f:id:key_amb:20150430202447p:plain

特徴

README.md から移行しやすいように、トップページで _index.md をレンダリング
ヘッダメニューの項目を設定可能に
目次をサイドバーに表示

最低限という感じですが、小〜中規模なドキュメントなら、このぐらいで十分なんじゃないかなという気もします。

デザインは Bootstrap 先生に任せました。ミニマムなものにスリム化したい気もしますが、そこを頑張りたいわけではなかったので。

お試しあれ。

余談

Hugo の既存のテーマで GitHub - nilproductions/hugo-bootswatch: Hugo bootswatch theme というのもあって、まさしく Bootstrap を使ったドキュメンテーション用のテーマのようです。
が、メニューが Section ベースで、目次がなかったりとかなり簡素なものでした。

サイト内検索ができるといいですが、この辺のディスカッションを見ると、Hugo自体にその機能が入ることはなさそうです。
Hugo のサイト自体もそうですが、Google カスタム検索で賄えるケースもあるかもしれません。

https://github.com/spf13/hugoThemes/ に Pull-Request を送ると作ったテーマをリストに入れてもらえるようです。
気が向いたら Pull-Request を送ってみようかなと思っています。

(5/1 追記)

Pull-Request してみたら、あっさりマージしてもらえました。