weblog of key_amb

主にIT関連の技術メモ

ドキュメンテーション用の Hugo のテーマ "bootie-docs" を改善しました #gohugo

Bootie Docs はちょうど一年前ぐらいにドキュメンテーション用の静的サイトジェネレータがほしくて作った Hugo*1 の Theme (テンプレート)です。
当時の記事はこちら:

色々イケてないところがあったので、GW 連休中にがっつり手を入れて、機能追加もしましたので、お知らせします。

ほとんど CHANGELOG に書いた内容に相当します。

※5/7 更に変更点有り、追記しました。

デフォルトアイコンがかっこ悪い

見るたびに気持ちが萎えていたので、パワーポイントでちょっと図形をいじって、こんな感じ になりました。
雰囲気おしゃれになったかなと。

依存コンポーネントを最新版にアップデートし、シンタックスハイライトのスタイルを選択可能に

Bootstrap と jQuery (v1系) と highlight.js を最新化しました。
highlight.js については、config.toml の params.highlightStyle という設定値で好みのスタイルを選べるようにしました。
どんなスタイルがあるかは こちら に highlight.js のデモページがありますので、ご参考まで。

サイトマップ的なページを作った

/index/ というパスで全ページリストを表示できるようにしました。
Hugo は自由にディレクトリを切ってページを階層化できるのですが、2段階までは階層表示できます。
やり方は Bootie Docs の マニュアルサイト をアップデートしていますので、こちらをご確認下さい。

サイドバーをスクロールに追従するようにした

久しぶりに JavaScript を書きました。
Chrome, Firefox, Safari では動作確認しました。
※もっといい書き方があったら教えてほしい^^;

5/7 追記:

  • ケータイなど幅の狭いブラウザで表示が崩れてしまっていたのを修正し、元通りのレスポンシブな表示になるようにしました。

Google のサイト検索機能を使った検索フォームを付けられるようにした

config で params.searchDomain を設定した場合のみ、有効になります。

(5/7 追記)メニューのテキストを変更可能に、任意ページをメニューに追加可能に

今までは content/ 直下のページ or section しかメニューに足せなかったのですが、v1.1.0 で任意ページを足せるようにしました。
これにより config の書き方が変わりましたので、ご注意下さい。

Before v1.0.x:

[params]
  mainMenu = ["about", "usage"]

After v1.1.0:

[[params.mainMenu]]
  name = "About"
  link = "about"

[[params.mainMenu]]
  name = "Usage"
  link = "usage"

TOML の Array of Tables という記法を使っています。
下の書き方も試したのですが、たぶん Hugo 内部で使われているパーサが inline table 記法に未対応で、エラーになってしまいました。

[params]
  mainMenu = [
    { name = "About", link = "about" },
    { name = "Usage", link = "usage" },
  ]

(5/7 追記) カテゴリ > ページの一覧をサイドバーやTOPページで表示するようにした

これにより、上述のサイトマップ的ページを設置する意義は薄れました^^;
まあ、お好みでどうぞ。

その他、細かいスタイルの改善

  • table にスタイルが付いてなかったので、bootstrap の .table-striped, .table-bordered 相当のスタイルを付けて GitHub っぽく見えるようにした。
  • コードブロック内が折り返しされていたので、折り返さないように。*2
  • ページ幅が最大 970px だったが、1200px に変更

自分のプロダクトのドキュメントサイトも更新しました

見本としてご参考にどうぞ。

fireap は GitHub Wiki から引っ越しました。
Markdown 形式なので引越しそのものは簡単でした。
(※その過程で色々スタイルのイケてないところを見つけたので v1.0.1 => v1.0.2 になりましたが。)

終わりに

ドキュメント用のテーマとして、より使いやすくなったと思います。
Markdown でドキュメントを管理したいときに、選択肢としてご一考いただければ幸いです。

既にお使いの方は、ぜひアップデートしてみてください。*3

Enjoy!

*1:Golang 製の静的サイトジェネレータ

*2:参考: Bootstrapを使った場合にpreタグを改行させたくない - Qiita

*3:5/8 本家 hugoThemes にも最新版が取り込まれました :D https://github.com/spf13/hugoThemes/pull/133