Hugo — 静的サイトを高速生成
Markdown記法のテキストをHTMLに変換する、静的ウェブサイト生成プログラム。 公式ドキュメントが充実しているので基本的にそれに従えば簡単にできる。
- https://gohugo.io/overview/introduction/
- https://discuss.gohugo.io/
- https://github.com/gohugoio/hugo
高速さとシンプルさに惹かれてSphinxから移行し、 本サイトもHugoでビルドしている。 オフラインの研究ノートとしても有用。
Quickstart
http://gohugo.io/overview/quickstart/
-
インストール方法はいろいろ用意されてる。 例えば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://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