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

Posts

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

参考