前回の「Static Site Generator」エントリの続きです。
Static Site Generator の Hugo を使ってみました。
ビルドが爆速なのがすごく良いんですが、いくつかはまったのでまとめておきます。
実際には12個もはまってないんですが。
1. デフォルトのテーマ（theme）が設定されていないのでいきなり起動しても何も表示されない
Hexoの場合
npm install hexo-cli -g
hexo init blog && cd blog && npm install
hexo server
とするだけで、デフォルトで設定されたlandscapeというthemeで起動し、
http://localhost:4000/ を開けばトップページが見れます。
Hugoの場合
brew update && brew install hugo
hugo new site bookshelf && cd bookshelf
hugo server
という手順を踏んでサーバを起動しただけでは、何も表示されません。
thmemeが何も設定されていないからです。*1
2. テーマ（theme）って何？
デザイン・テンプレートです。
既存のthemeを活用してベースのデザインを作成できます。
もちろんカスタマイズすることができます。
HTMLやCSSやJSなどのファイル群で構成されます。
JekyllやHexoでもthemeという用語を使うので、全然はまりどころじゃないかもしれないですね。
3. themeはGithubなどからcloneしてこないといけない
themeを設定するにはthemesディレクトリ配下に、OSSとしてGitHubに公開されているthemeをgit cloneしてくるのが、最も手っ取り早い方法です。*2
例えば、以下のようにanybodyhomeというthemeをインストールします。
mkdir themes
cd themes
git clone https://github.com/lasseborly/anybodyhome.git
そして、適用するthemeを以下のように指定してサーバを起動します。
hugo server --theme=anybodyhome
これで http://localhost:1313/ ((ローカルの1313ポートが既に使用されている場合は、適当なエフェメラルポートがアサインされます。コマンドの出力で確認してください。))を開けばトップページが表示されます。
4. themeは実はまとめて全てcloneしてこれる。
themesディレクトリにはいくつでもthemeをcloneしておけます。
https://github.com/spf13/hugoThemes リポジトリにはOSSで公開されているthemeがまとまっており、これをcloneすればまとめてインストールできます。
git clone --recursive https://github.com/spf13/hugoThemes.git themes
あとは、hugo server --theme=<試したいtheme名>で色々試してみて気に入ったものを見つけたらconfig.tomlにtheme = "anybodyhome"などのように記述すればOKです。
起動時に--theme指定がない場合にはconfig.tomlの設定が使用されます。
5. 記事のメタデータの書式がToml
hugo new post/foo.mdと実行すると/content/post/foo.mdという記事のファイルの雛形が生成されます。
このファイルの先頭には、自動でメタデータが書かれています。
こんな感じです。
+++
date = "2016-09-04T16:01:08+09:00"
draft = true
title = "foo"
+++
これはTomlという形式です。
メタデータには、他にcategoriesやtags、slugなどなどの値があるのですが、
categoriesやtagsには複数の値が指定でき、その場合はTomlの配列の形式で書きます。
例えばこんな感じです。
+++
date = "2016-09-04T16:01:08+09:00"
lastmod = "2016-09-11"
draft = true
title = "foo"
categories = ["programming", "golang"]
tags = ["golang", "toml", "hugo"]
notoc = true
+++
6. 設定ファイルもToml
config.tomlという見慣れない拡張子のファイルがサイト全体の設定ファイルです。
RustのビルドツールのCargoでも採用されているし、実は結構メジャーなのかもしれません。
- Tomlの基本の構文は、改行区切りで設定を列記していくかたちです。
iniとかに少し近いです。
- 行コメントの記号は、
#です。
"""と"""で囲ってやれば複数行の文字列リテラルとなります。- 添字配列は、
["apple", "orange", "grape"]のように[]で記述します。
- Tomlが気に入らない場合は
config.yamlやconfig.jsonなどを用意すればtoml以外の形式も使用可能です。
Tomlは連想配列の構文などもあり、シンプルながらかなり表現力豊かですが、Hugoの設定としては上記を知ってればだいたい大丈夫な気がします。
Tomlの詳しい文法はQiitaにもいくつか投稿されています。
7. 記事のURLの変え方
設定ファイルの[permalinks]以下にpostという設定値を追加すればOKです。
[permalinks]自体がなかったらそれも追加してください。
例えばファイル名の拡張子を除いた文字列をURLに使用するなら:filenameというパラメータを使います。
[permalinks]
post = "/post/:filename"
日付やメタデータのtitle値を使うならこんな感じ。
[permalinks]
post = "/:year/:month/:title/"
8. テンプレートのカスタマイズ
themeでインストールしたテンプレートをカスタマイズ/拡張し管理する方法は２つあると思います。
１つは、themeの中で使われているテンプレート・ファイルのうち上書きしたいものをlayouts/にコピーし、好きに書き換えることです。
例えば、
themes/anybodyhome/layouts/partials/footer.htmlというファイルは全体のフッタ部分を構成するHTMLのテンプレートです。
これを
layouts/partials/footer.htmlにコピーして編集すればOKです。
ただし、この方法はテンプレート・ファイル単位での上書きになってしまうところがちょっと嫌です。
なぜかというと、さっきのfooter.htmlならまだ良いのですが、記事自体のページのテンプレートのHTMLをほんのちょっと修正したいような場合にもthemes/anybodyhome/layouts/_default/single.htmlという記事全体のHTMLのテンプレートをまるまるコピーしないといけないからです。
適切にHTMLがパーツ化されていて、修正したい部分が小さなパーツになっている場合には悪くないんですが。
２つめは、使用するthemeをGitHub上でフォークして修正し、それをgit cloneして使用する方法です。
こっちのほうが差分が分かりやすくなるので全然おすすめだと思います。
9. GolangのTime.timeの日付フォーマット表記が独特
Hugoで採用されているGolangのテンプレートエンジンの構文は、私は初めてだったので全然慣れませんでした。
しかし、既存のthemeを使う分には見よう見まねでも結構なんとかなります。
1点はまったのが日付のフォーマットの変更です。
Javaなんかだと%YYYY-%MMなどのように%を使ってフォーマットを指定しますが、GolangではMon Jan 2 15:04:05 -0700 MST 2006のように実際の日付の値を使用してフォーマットを指定します。
つまり、
Mon Jan 2 15:04:05 -0700 MST 2006
この日時が重要なようです。
１月なのを勝手に２月とか３月にしてはいけません。
例えば、記事のページ内にメタデータで記述したdate値を表示するテンプレートの構文は
{{ .Date.Format "2006/01/02" }}
のようになります。
これは、テンプレートエンジンの仕様というよりはGolangのtimeパッケージの仕様のようです。
10. 404ページ
デフォルトだと指定したURLのリソースが見つからない場合用の404ページがありません。*3
GitHub Pages でホストする場合には、layouts/404.htmlを用意しておけばOKです。
404ページとして生成・使用されます。
layouts/404.htmlは単にルートに404.htmlを生成するだけなので、GitHub Pages以外の環境でもWebサーバを適切に設定すれば上記のファイルを404ページとして使用可能です。
詳しくはhttps://gohugo.io/templates/404#automatic-loadingを参照してください。
11. References
もはやはまりどころでは全くないのですが、カスタマイズしたりする時によく参照するリファレンス達です。
12. 動作が早過ぎる
最後に。
むしろ良いことなんですが、最初にhugo new site bookshelfしたとき、レスポンスが早過ぎて失敗してるのかと思いました。
スリープ入れるようにPullRequestすると安心できるかもしれません。
という感じで、皆様幸せなHugoライフを！
