weblog of key_amb

主にIT関連の技術メモ

Hugo で "bootie-docs" というドキュメンテーション用のテーマを作った #Hugo

※2016/4/6 記事更新

こちらです。

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

Motivation

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

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

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

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

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 してみたら、あっさりマージしてもらえました。