HUGOのテンプレートファイルの動きを確認する

レイアウト参照ディレクトリの優先順位を理解する

HUGOのレイアウト参照方法にはルールがあります。

HUGOはコンテンツの静的ファイルを生成する際に下記の順番でレイアウトをファイルを探します。

1. /layouts/タイプ/ディレクトリを探す
2. /layouts/_default/ディレクトリを探す
3. /themes/テーマ名/を探す

簡単にまとめると、「個別タイプ > デフォルト > テーマ内 」の順番で探していきます。ここがすべての基準です。

ホームページ（サイトルート）は例外で、ホームの場合はまず「/layouts/index.html」が参照なければ、上記の順番で「list.html」を探します。

テーマを使う時は要注意

config.tomlで、使用するテーマを指定していても、layoutディレクトリ内に対応するレイアウトファイルがあれば、そちらが優先されてしまいます。

個別にレイアウトをカスタマイズすることがないのであれば、layoutディレクトリ内は空にしておくほうが安全です。

レイアウト参照ファイルの優先順位を理解する

ディレクトリの読み取り順の次は、レイアウトをファイルの参照順をみていきましょう。

リストページの場合

HUGOにおけるリストページとは、その名の通り「ページの一覧ページ」です。HUGOで作成された静的サイトにおいて、リストページとなるのは

1. ホームページ
2. セクションのインデックスページ（example.com/section/など）

の2種類です。

本来は、tagやcategories直下も同じなのですが、こちらはタクソノミールールが適用されているので、list.htmlは適用されないので注意が必要です。

リストページのレイアウトファイルの参照順は下記のようになります。

ホームページの場合

/layouts/index.html
/layouts/_default/list.html
/themes/テーマ名/layouts/index.html
/themes/テーマ名/layouts/_default/list.html

ホームの場合は、多くのケースで/layouts/index.html を設定すると思いますが、list.htmlを作っておけば/layouts/index.html はなくても動作するとお覚えておけば良いでしょう。

セクションの場合

セクションの場合は少し複雑です。

まず、セクションの一覧をページを出力するには、content直下の各セクションディレクトリ内に「_index.md」がないと一覧が生成されません。

「_index.md」がある場合は、下記のルールでレイアウトを決定します。

/layouts/section/セクション名.html
/layouts/セクション名/list.html
/layouts/_default/section.html
/layouts/_default/list.html
/themes/テーマ名/layouts/section/セクション名.html
/themes/テーマ名/layouts/セクション名/list.html
/themes/テーマ名/layouts/_default/section.html
/themes/テーマ名/layouts/_default/list.html

ルールを見ると、

1. セクション名が優先
2. ディレクトリよりもセクション名ファイルが優先
3. なければsection.htmlを見に行って
4. 見つからなかったら、同じ一覧系のlist.htmlを探す

となっています。

ホームと同じで、list.htmlがあればなんとかなる感じになっています。

シングルページ系の場合

シングルページ系とは、上記の一覧系に適用されないページ全般です。

/layouts/タイプ名/レイアウト名.html
/layouts/セクション名/レイアウト名.html
/layouts/タイプ名/single.html
/layouts/セクション名/single.html
/layouts/_default/single.html
/themes/テーマ名/layouts/タイプ名/レイアウト名.html
/themes/テーマ名/layouts/セクション名/レイアウト名.html
/themes/テーマ名/layouts/タイプ名/single.html
/themes/テーマ名/layouts/セクション名/single.html
/themes/テーマ名/layouts/_default/single.html

タイプ名とは、「content」ディレクトリ直下のディレクトリです。

つまり、「/content/blog/」内のコンテンツは、「layout/blog/」ディレクトリから順番に参照していきます。

わかりづらいのが、「/layouts/セクション名/レイアウト名.html 」のケースや「/layouts/セクション名/レイアウト名.html 」のケースで、例えば「content/blog/hugo/」という構成だった場合、

/layouts/blog/single.html
/layouts/blog/list.html
/layouts/blog/term.html

と言った形で、blogタイプだけでオリジナルのレイアウトが作れますし、

/layouts/hugo/single.html
/layouts/hugo/list.html
/layouts/hugo/term.html

と言った形で、セクションだけで縛ったレイアウトも作ることができます。

これらのレイアウトファイルが無かった場合は、基本的にはsingle.html をタイプ->セクションの順に探していく形になります。

タクソノミー系の場合

最後にタクソノミー系です。

こちらは比較的シンプルで、タクソノミー名.html->taxonomy.html ->list.html の順で参照されるのでわかりやすいでしょう。

/layouts/taxonomy/タクソノミー名.html
/layouts/_default/taxonomy.html
/layouts/_default/list.html
/themes/テーマ名/layouts/taxonomy/タクソノミー名.html
/themes/テーマ名/layouts/_default/taxonomy.html
/themes/テーマ名/layouts/_default/list.html

HUGOのテンプレートの動きを見てきました。

わかりづらいのは、リスト系の動きで、ここはcontentディレクトリ内のファイル構成も関連してくるので、シンプルなテーマなどで自分で変更して、動きを掴むのが良いでしょう。