Hugo の記事ファイルのフロントマターで使用するレイアウトを制御する (type, layout)

2020-05-04

フロントマターでのレイアウト指定

Hugo では、記事ファイル (.md) のレンダリングにどのレイアウトファイルを使用するかは、content ディレクトリ以下にどのようなパスで .md ファイルを配置したかによって決まります。ほとんどのページではこれで十分なのですが、あるページだけ特殊なレイアウトを使用したい ことがあります。例えば、検索ページや、新着記事リストのページなどです。このような場合は、Markdown ファイルのフロントマターで、type プロパティや layout プロパティを指定することで、使用するレイアウトファイルを制御することができます。

type プロパティ: コンテントタイプを指定します。デフォルトでは、content ディレクトリ以下のディレクトリ名が使われます（参考: Content Types | Hugo）。
layout プロパティ: レイアウト名を指定します。デフォルトでは、ページの種類によって section.html（セクションテンプレート）や single.html（シングルページテンプレート）が使用されます。

これらの値の組み合わせによって、そのページをレンダリングするときに使用するレイアウトファイル（テンプレート）が次のように決まります。

layouts/<タイプ名>/<レイアウト名>.html

実際には、すべてのコンテントタイプで共通のレイアウトファイルを使えばよいことが多く、そのようなケースでは layouts/_default/single.html といったレイアウトファイルを配置します（タイプ名として _default 指定されたかのように振る舞います）。複数のレイアウトファイルが存在する場合に、どのレイアウトファイルが選択されるかのルールは下記を参照してください。

参考: レイアウト用のテンプレートの種類を理解する

通常、コンテントタイプとレイアウトファイル名は、ディレクトリ構造と Markdown ファイル名によって決まるようになっています。例えば、次のような感じです。

Markdown フィイル名	コンテントタイプ	レイアウトファイル
`content/foo/_index.md`	`foo`	`section.html` や `list.html`
`content/foo/page1.md`	`foo`	`single.html`
`content/bar/page2.md`	`bar`	`single.html`
`content/foo/bar/page3.md`	`foo`	`single.html`

フロントマターで type と layout を指定することにより、これらのルールを無視して、強制的に使用するレイアウトファイルを変更することができます。例を見た方が分かりやすいので、ここでは、「新着一覧」のページをサンプルとして作ってみます。

☝️ ワンポイント記事の一覧を表示するくらいであれば、通常はショートコードで出力してしまった方が簡単です。ここでは、特定のページだけレイアウトを大きく変更する必要があると想定しています

使用するレイアウトファイルを指定する例

下記のテンプレートでは、更新日時が新しい順に、5 件分の記事をリスト表示しています。このレイアウトは、「新着一覧」のページでしか使わない 特殊なレイアウト なので、レイアウトファイル自体も layouts/special/latest.html という特殊なパスに作成することにします。このレイアウトファイルは、コンテントタイプとして special、レイアウト名として latest が設定された記事ファイルに適用されます。

layouts/special/latest.html（抜粋）

<ul>
  {{- range first 5 .Site.RegularPages.ByLastmod.Reverse }}
    <li>
      <b><a href="{{ .RelPermalink }}">{{ .Title }}</a></b>
      <time>{{ .Date.Format "2006-01-02" }}</time>
    </li>
  {{- end }}
</ul>

次に、記事一覧のページを出力するための Markdown ファイルを作成します。コンテントタイプとレイアウト名はフロントマターで指定するので、Markdown ファイルはどのようなパスに配置しても構いません。ここでは、content ディレクトリ直下に配置することにします。

content/latest.html

---
title: "新着一覧"
type: "special"
layout: "latest"
---

（本文は空っぽで OK）

本文はレイアウトファイルの方で出力される内容だけでいいので、Markdown ファイルにはフロントマターだけを記述します。コンテントタイプとして special、レイアウト名として latest を指定しているので、layouts/special/latest.html というパスに配置したレイアウトファイルが使用されることになります。

もちろん、記事ファイルを配置するパスによって、使用するレイアウトファイルをうまく制御するのでも OK です。例えば、content/latest/_index.md というパスに Markdown ファイルを配置すれば、フロントマターで type や layout を指定しなくても、レイアウトファイルとして layouts/latest/section.html（あるいは list.html）が使用されます。

2020-05-04