Hugoのテンプレートを0から作成する為の基礎

こんにちはnasustです。 今回の記事から、Hugoのテンプレートを0から作成する為の基礎を解説します。

Hugoのテンプレートは一端理解すればシンプルなので簡単です。

特徴

特徴は次の通りです。

  • MarkdownからHTML変換に用いるテンプレートは、ディレクトリやファイル名のルールに則ってマッチングされ使用されます。
  • テンプレートにはページ用やリスト用などの種類があります。
    • ページ用とは、Markdownを1つのHTMLページに変換するテンプレートです。
    • リスト用とは、トップページやカテゴリーのアーカイブなど記事の要約など時系列で並べて表示するテンプレートです。
  • テンプレートは変数をHTMLに出力する機能があります。
    • {{ }}で囲まれた変数がHTMLの文字として出力されます。
    • 変数には組み込み変数があり、それにタイトルや文章が格納されます。
  • テンプレートにはifやrangeなどの制御構文があります。

大まかな特徴はこの通りです。これらを理解すればテンプレートを作成するには難しくありません。

変数について

Hugoの変数について解説します。以下の例で説明します。

{{ $var := "こんにちは" }}
<p>
    {{ $var }}
</p>
html

{{ $var := }}は変数を宣言しています。:=は初期の値を代入しています。{{ $var }}は文字列として出力されます。

<!-- 結果 -->
<p>
    こんにちは
</p>
html

変数はデフォルトでHTMLエスケープされます

{{ }}はデフォルトでHTMLのエスケープされます。

{{ $var := "<span>こんにちは</span>" }}
<p>
    {{ $var }}
</p>
html
<!-- 結果 -->
<p>
     &lt;p&gt;こんにちは&lt;/p&gt;
</p>
html

エスケープしたく無い場合

エスケープしたく無い場合は、パイプという機能を使用します。

{{ $var := "<span>こんにちは</span>" }}
<p>
    {{ $var | safeHTML }}
</p>
html
<!-- 結果 -->
<p>
     <span>こんにちは</span>
</p>
html

パイプという機能を使用することで、そのまま出力することが出来ました。|はパイプを表しており、変数など加工したい場合に使用します。safeHTMLは変数出力のエスケープを解除します。 他の機能などは別の記事で解説します。

変数の上書き

変数は別の値を代入できます。

{{ $var := "こんにちは" }}
<p>
    {{ $var = "こんばんは" }}
    {{ $var }}
</p>
html
<!-- 結果 -->
<p>
     こんばんは
</p>
html

変数を上書きする場合は=を使用します。

ページ特有の組み込み変数

テンプレートには、変換時に使用する組み込みの変数があります。

<div class="content">
    {{ .Content }}
</div>
html
<!-- 結果 -->
<div class="content">
    こんにちはnasustです。今回の解説は・・・
    〜〜
    〜〜
</div>
html

.ContentはMarkdownの文章です。 これは変数出力する時にHTML変換されます。

このようにページ特有の組み込み変数など用いてHTML出力してきます。 他の組み込み変数については他の記事で解説します。

制御構文

制御構文はifrangeなどあります。

if

ifは他のプログラムと同じように比較して真や偽の場合の プログラムを実行できます。

{{ $var := true }}
{{ if $var }}
    <p>
        こんにちは
    </p>
{{ else }}
    <p>
        こんばんは
    </p>
{{ end }}
html
<!-- 結果 -->
<p>
     こんにちは
</p>
html

$varをfalseにすると偽の処理が行われます。

<!-- 結果 -->
<p>
     こんばんは
</p>
html

お気づきかと思いますが、ifは、{{ if }}{{ end }}で囲まれています。 これはHugoのブロック構文の仕様になっています。

range

rangeは繰り返し処理を行います。

{{ $var := slice 1 2 3 4 5  }}
<ul>
{{ range $var }}
    <li>{{ . }}</li>
{{ end }}
</ul>
html
<!-- 結果 -->
<ul>
     <li>1</li>
     <li>2</li>
     <li>3</li>
     <li>4</li>
     <li>5</li>
<ul>
html

sliceはスライスを作成する関数です。

Hugoは、これらの変数と制御構文を利用してテンプレートを記述します。

テンプレートのマッチングについて

Hugoのテンプレートのファイルは、lyoutsディレクト以下にある*.htmlの HTMLファイルが使用されます。

その中でlayout/_defaultディレクトリは、全てのテンプレートのデフォルトを 格納する場所です。

Hugoで最低限用意するテンプレートは以下の2つです。

  • layout/_default/single.html
  • layout/_default/list.html

single.htmlはMarkdownの文章をHTMLに変換するテンプレートです。

list.htmlはブログのアーカイブページなど、各記事へのリンクを作成するテンプレートです。

この2つのテンプレートが最低限です。トップページやアーカイブページ、 記事のページの全てを賄えます。

実際テンプレートを作成する場合は、 トップページなど特別なレイアウトを用意することになると思います。 その場合はlayout/index.htmlを用意します。

用意されてない場合は、list.htmlを使用しますが、用意すると優先してindex.htmlのテンプレートを使用します。

同じようにブログ用のレイアウトを使用したい場合は、layout/post/single.htmlやlayout/post/list.htmlを用意します。

※ブログの記事の場所がcontent/postである場合

Hugoのテンプレートのマッチングは、このようにページの具体的な場所に近いテンプレートを優先的に使用します。

Hugo’s Lookup Order | Hugo

Hugoのドキュメントで詳しくマッチングルールが解説されています。

以下のリストはsingle.htmlの例です。

  • layouts/posts/single.html.html
  • layouts/posts/single.html
  • layouts/_default/single.html.html
  • layouts/_default/single.html

など優先度が記述されています。上ほど優先度が高く、下ほど低いです。

次回

次回は、single.htmlやlist.htmlを実際に作成しながら解説します。

prevnext