Heavy Watal

Hugo — 静的サイトを高速生成

Markdown記法のテキストをHTMLに変換する、静的ウェブサイト生成プログラム。 公式ドキュメントが充実しているので基本的にそれに従えば簡単にできる。

高速さとシンプルさに惹かれてSphinxから移行し、 本サイトもHugoでビルドしている。 オフラインの研究ノートとしても有用。

Quickstart

http://gohugo.io/overview/quickstart/

設定

https://gohugo.io/overview/configuration/

config.toml

Theme

http://themes.gohugo.io/

デフォルトのテーマというものが存在しないのがちょっと厳しい。 ユーザーによっていろいろ投稿されてるけどほとんどがブログ用途。 ということで非ブログ用に簡単なものを自作して使っている:

https://github.com/heavywatal/hugo-theme-nonblog

Performance

https://gohugo.io/troubleshooting/build-performance/

ページによって内容が変わらないテンプレートは partial の代わりに partialCached を使う。 ビルドするときに --templateMetrics --templateMetricsHints オプションを付けるとどのへんを変えたら良いか教えてくれる。

Content

Markdown

CommonMark
“Markdown"の正式な仕様というものが存在せず、 いくつかの方言(flavor)が乱立していたが、 現在ではこれが事実上の標準仕様となりつつある。 2017年からGFMがこれに準拠することになったのもよかった。
GitHub Flavored Markdown (GFM)
CommonMarkに準拠しつついくらかの機能を追加したもの。 Atomでも標準サポート。 基本的な書き方はGitHub Helpのページが読みやすい。
Blackfriday
HugoのMarkdownエンジンは長らくこれだった。 CommonMark準拠じゃないし、 リストまわりでの不具合が放置されてるし、 などなど不満が募るうちにGoldmarkに取って代わられた。
Goldmark
2019年末からHugoはこっちに移行した。 基本的にはCommonMark準拠だけど、 デフォルト設定での生HTMLコードの扱いがちょっと変。

Front matter

タイトルや日付などのメタデータをファイルの先頭で記述する。 YAMLやJSONでもいいけど、 TOMLのほうが将来性ありそう。

閲覧・公開方法

Hugo Server

付属の簡易サーバーを起動。

hugo server -D -w -s /path/to/source
open http://localhost:1313/

localhost (Mac)

public/ 以下に生成されるファイルを /Library/WebServer/Documents にコピーすれば localhost で閲覧できる。 ユーザーの ~/Sites/ をドキュメントルートにする方法でもいいが、 単にシンボリックリンクを張るほうが楽ちん。

cd /Library/WebServer/
sudo mv Documents Documents.orig
sudo ln -s ~/Sites Documents
cd /path/to/site-source
hugo
rsync -au --delete --exclude='.git' public/ ~/Sites/
open http://localhost/

GitHub Pages

public/ 以下に生成されるファイルをしかるべきrepository/branchに置くだけ。

See Git