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

正式な仕様が未だに存在せず、いくつかの方言(flavor)が存在する。

CommonMark
標準仕様決定に向けて議論中。
GitHub Flavored Markdown (GFM)
いま最もよく書かれているのはこれかな? Atomでも標準サポート。 基本的な書き方はGitHub Helpのページが読みやすい。 CommonMarkに準拠することが2017年に発表された
Blackfriday
HugoのMarkdownエンジンはこれ。 残念ながら上記2つとも微妙に違うが、 開発中のv2ではCommonMark準拠の流れもあるっぽい。

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