HUGOのテンプレートファイルの優先順位を理解する

Blog

HUGOでは、contentの下にあるMarkdownファイルを、テンプレートファイルを使用してHTMLに変換しています。

レンダリングに利用するテンプレートファイルは、ページの種類（コンテンツファイルのパス）に応じて用いられるファイルが異なります。 この記事では、サイトのコンテンツがどのテンプレートファイルを使用してレンダリングされるかについて説明します。

動作を確認した環境

  • HUGO v0.58.2/extended

コンテンツファイルの構成

contentディレクトリが、次のようなファイル構成だったとします。

.
├── ...
├── content
│   ├── _index.md # Home page
│   ├── page-01.md # Single page
|   ├── posts
|   |   ├── _index.md # Section page
|   |   ├── post-01.md # Single page
|   |   └── post-02.md # Single page
|   └── quote
|   |   ├── quote-01.md # Single page
|   |   └── quote-02.md # Single page
├─ ...
  • Home page
    • content直下にある_index.mdファイルは、「Home page」と呼ばれ、サイトのトップページにあたるページになります。
  • Section pages
    • contents次のディレクトリは「Section」と呼ばれ、そのディレクトリ直下の_index.mdはセクションページと呼ばれます。
  • Single page
    • 個々の記事ページにあたるページです。
  • List pages
    • コンテンツの一覧を表示することを目的としたページです。
  • Taxonomy Terms Pages
    • HUGOでは、Taxonomy（タクソノミー）と呼ばれる項目を記事ファイルのFront matterにつけて、記事をグルーピングできます。たとえば、「タグ」や「カテゴリ」といった項目がTaxonomyにあたります。また、Taxonomyに割り当てられる具体的な値をTermと呼びます。たとえば、記事に「開発」というタグを付け足場合、「開発」がTermにあたります。
    • Taxonomy Terms Pagesは、Taxonomyに割り当てられたTermをもつ記事の一覧ページです。

テンプレートファイルを参照するディレクトリの優先順位

HUGOは、コンテンツをHTMLに変換するとき、あるルールにもとづいてテンプレートファイルを参照しています。

HUGOは、大まかには次の優先度でテンプレートファイルのあるディレクトリを探索します。

  1. layouts/以下
  2. themes/{テーマ名}/layouts以下

探索しているディレクトリのうち、後述するファイル名の優先順位にもとづいて最初に見つかったファイルがテンプレートとして利用されます。 見つからなければ、次に優先度の高いディレクトリでファイルを探します。 最後まで見つからなければ、そのコンテンツはレンダリングされないので、真っ白なページになります。

このディレクトリの優先順位があります。 テーマファイルを一部修正したいときはlayouts以下へ変更したいテンプレートファイルと同名のファイルを置くと、そのページのレイアウトだけを独自に変更できます。

テンプレートファイルを参照するファイル名の優先順位

Home page

Home pageはホームページテンプレートを使って、HTMLへレンダリングされます。

ホームページテンプレートは、次のファイルのうち、最初に見つかったファイルが利用されます（参考：Layout Lookup for Home Page）。

  • index.html
  • home.html
  • list.html
  • _default/index.html
  • _default/home.html
  • _default/list.html

list.htmlは、List pageを生成します。 トップページがランディングページではなく記事一覧のみでよい場合は、index.htmlやhome.htmlを作らずに、list.htmlだけを作ります。

Section page

Section pageは、セクションテンプレートを使って、HTMLへレンダリングされます。

セクションテンプレートは、次のファイルのうち、最初に見つかったファイルが利用されます（参考：Layout Lookup for Section Page）。

  • {セクション名}/{セクション名}.html
  • {セクション名}/section.html
  • {セクション名}/list.html
  • section/{セクション名}.html
  • section/section.html
  • section/list.html
  • _default/{セクション名}.html
  • _default/section.html
  • _default/list.html

Home pageと同様に、セクションにランディングページを作りたい場合は、section.htmlを作ります。 {セクション名}/{セクション名}.htmlや{セクション名}/section.htmlのように、セクション名ごとに別々のランディングページを作ることもできます。

Single page

Single pageは、セクションテンプレートを使って、HTMLへレンダリングされます。

シングルページテンプレートは、次のファイルのうち、最初に見つかったファイルが利用されます（参考：Layout Lookup for Single Page）。

  • {セクション名}/single.html
  • _default/single.html

参考