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

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

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

Quickstart

https://gohugo.io/getting-started/quick-start/

インストール方法はいろいろ用意されてる。例えばMacならHomebrewで一発: brew install hugo

バージョンを細かく指定したりソースコードを改変したりしたい場合はgitから:
```
export GOPATH=${HOME}/.go
export PATH=${PATH}:${GOPATH}/bin
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended
```
--tags extended はSASS/SCSS対応版をコンパイルするオプション。
骨組みを作る:
```
cd path/to/site
hugo new site .
```

ページをMarkdownで書く:

hugo new about.md

+++
date = 2016-02-26T19:10:22+09:00
title = "About"
+++

## Heading

normal *italic* **bold**

テーマをとりあえず全部インストール:

git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes

ウェブサーバーを走らせる:
```
hugo server -w D -t hyde
```
ブラウザから http://localhost:1313/about にアクセスしてみる。監視オプション -w を付けておけば、ファイルの変更がすぐに反映される。

設定

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

config.toml

Theme

https://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に準拠しつついくらかの機能を追加したもの。基本的な書き方は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/ に配置すれば http://localhost で閲覧できる。ユーザーの ~/Sites/ をドキュメントルートにする方法でもいいが、単にシムリンクを張るほうが楽ちん。

ls /Library/WebServer/
sudo mv /Library/WebServer/Documents /Library/WebServer/Documents.orig
sudo ln -s ~/path/to/public /Library/WebServer/Documents
open http://localhost/

5秒待たされる問題を避けるため KeepAlive Off を設定しておく。 /etc/apache2/httpd.conf を直に書き換えるか、 /etc/apache2/other/keepalive.conf のようなファイルを作り、 sudo apachectl graceful で変更を反映。

GitHub Pages

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

See Git