Hugoでテーマ自作をしていると、テンプレートファイル (page.html など) の中に {{ }} で囲まれた謎の文字列がたくさん出てきますよね。
この暗号のように見える部分は、 Hugoのテンプレート言語（Go HTML Template） と呼ばれる仕組みです。

「この変数はどこに設定された値なの？」
「どんな時にどの関数を使えばいいの？」

そんなテーマ開発初心者の疑問を解決するために、このチュートリアル内で頻繁に登場した重要な変数や、覚えておくと便利な関数を一覧化してまとめました。辞書代わりに活用してください！

1. ページ変数 (Page Variables)

記事ごとの情報が入っている変数です。
記事のファイル (.md) の Front Matter に書いた内容が、そのまま変数になって使われます。

{{ .Title }}

記事のタイトルを表示します。

{{ .Content }}

記事の本文を表示します。

{{ .Date }}

記事の日付データです。

{{ .Permalink }}

記事の完全なURLです。

{{ .IsHome }}

「今見ているのはトップページか？」 を判定します。

{{ .IsPage }}

「通常記事（個別ページ）か？」 を判定します。

  • ブログ記事 (page.html が使われるページ) なら true です。
  • WordPressなどの is_single() に相当します。

{{ .IsSection }}

「一覧ページ（セクション）か？」 を判定します。

  • content/posts/ の直下にあるような、記事の一覧ページで true になります。

{{ if eq .Kind "term" }}

「タグやカテゴリーの一覧ページか？」 を判定します。

  • Hugoには IsTag や IsCategory という変数は残念ながらありません。
  • 代わりに「ページの種類 (.Kind)」が "term" かどうかで判定します。
  • /categories/tips/ のようなページで true になります。

{{ .Next }} / {{ .Prev }}

次の記事 / 前の記事の情報です。

  • 自動的に前後の記事を探してくれます（セクションに関係なく日付順）。
  • {{ .NextInSection }} / {{ .PrevInSection }} を使うと、「同じセクション（カテゴリー）の中だけで」 前後の記事を探すことができます。ニュース記事からTips記事に飛ばないようにしたい時などに便利です！
  • .Next.Title のように繋げて、隣の記事のタイトルを取得したりします。

{{ .Params }}

Front Matterに書いた独自のデータです。

  • タイトルや日付以外の、自分で決めた項目（例えば image = "..." など）は、すべて .Params の中に入ります。
  • {{ .Params.image }} のようにして取り出せます。
  • このサイトでの使用例: 【機能追加】アイキャッチ画像を表示する

{{ .Params.author }}

記事の執筆者情報です。

  • Front Matterに author = "名前" と書くと、この変数で取得できます。
  • チームブログなどで、「この記事は誰が書いたか」を表示したい時に使います。

{{ .ReadingTime }}

記事を読むのにかかる時間（分）です。

  • Hugoが自動計算してくれます（英語基準ですが、日本語でもそれなりに使えます）。
  • 「この記事は5分で読めます」のような表示に使います。

{{ .WordCount }}

記事の文字数です。

  • これもHugoが自動計算します。

{{ .Summary }}

記事の要約（サマリー）です。

  • デフォルトでは記事の冒頭70単語が自動的に抽出されます。
  • `

` というコメントを記事内に書くと、そこまでが要約になります。

  • 重要: 日本語が含まれる場合、hugo.toml に hasCJKLanguage = true を設定しないと、正しく要約が生成されません（全文が表示されてしまったりします）。

  • 注意: .Summary には <p> などのHTMLタグが含まれることがあります。メタディスクリプションなどで純粋なテキストが欲しい場合は、{{ .Summary | plainify }} のようにフィルタを通してタグを除去します。

  • .Paginator: ページネーション情報を持つオブジェクト。

    • .Paginator.Pages: 現在のページに表示すべき記事のリスト。
    • .Paginator.TotalPages: 全ページ数。
    • .Paginator.PageNumber: 現在のページ番号。
    • .Paginator.HasPrev / .HasNext: 前/次のページがあるかどうか。

2. サイト変数 (Site Variables)

サイト全体の設定情報が入っている変数です。
主に hugo.toml (設定ファイル) に書いた内容が反映されます。

{{ .Site.Title }}

サイトの名前（ブログ名）を表示します。

{{ .Site.BaseURL }}

サイトのトップページのURLです。

{{ .Site.RegularPages }}

サイト内の全ての「普通の記事」のリストです。

3. よく使う関数 (Functions)

変数に入っているデータを加工したり、特別な処理をするための命令です。

relURL

{{ "css/style.css" | relURL }}

Format

{{ .Date.Format "2006-01-02" }}

ref

[リンクだよ]({{< ref "posts/my-post.md" >}})
  • 記事へのリンクを自動生成します。
  • ファイル名を指定するだけで、正しいURLに変換してくれます。
  • Markdownファイル内でよく使います。
  • このサイトでの使用例: 文中リンクの付け方

range

{{ range ... }} ~ {{ end }}

partial

{{ partial "breadcrumbs.html" . }}

first

{{ range first 5 ... }}

fileExists

{{ if fileExists "static/images/hero.jpg" }}

4. 制御構文 (Control Structures)

条件によって表示を変えたりする構文です。

{{ if ... }} ~ {{ end }}

「もし～なら表示する」という条件分岐です。

{{ if .Next }}
  <!-- 次の記事がある時だけ表示される -->
  <a href="...">次の記事へ</a>
{{ end }}

{{ with ... }} ~ {{ end }}

「もし～があるなら、それを主役にして処理する」という便利な構文です。

  • if に似ていますが、ブロックの中では . (ドット) の意味が「その値そのもの」に変わります。
{{ with .Params.image }}
  <!-- .Params.image がある時だけ実行される -->
  <!-- ここでは「.」が「画像のパス」になる！ -->
  <img src="{{ . | relURL }}">
{{ end }}

{{ define "main" }} ~ {{ end }}

「ここがメインの中身だよ」と定義します。

{{ block "main" . }} ~ {{ end }}

「ここにメインの中身が入るよ」という場所を作ります。

5. 変数の定義 (Variable Definition)

テンプレートの中で、自分で変数を定義して使うこともできます。
長いパスを短くしたり、同じ値を何度も使う時に便利です。

:= (定義と代入)

{{ $style := "css/style.css" }}
<link rel="stylesheet" href="{{ $style | relURL }}">
  • $名前 := 値 で変数を定義します。
  • 変数名は必ず $ から始めます。
  • メリット:
    • コードが読みやすくなります。
    • VS Codeなどの自動整形(Formatter)による意図しない崩れを防げます（HTMLタグの中に複雑な記述を書かなくて済むため）。

6. コメント (Comments)

テンプレートの中に、メモを残したい時や、コードを一時的に無効化したい時に使います。

General Comments

{{/* これはコメントです。HTMLには出力されません */}}

Escaping Shortcodes

記事（Markdown）の中で、「ショートコードの書き方の例」を表示したい時に使います。
普通に書くと実行されてしまうので、/* */ でコメントアウトしてエスケープします。

{{< youtube "..." >}}

こう書くと、YouTubeは表示されず、そのまま文字として表示されます。

変数の意味を理解して自由自在にデータを引き出そう！

Hugoのテンプレート変数は最初は難解に感じるかもしれませんが、基本ルールはシンプルです。

  • ページ変数 (.Title など): その記事自身が持っているデータ
  • サイト変数 (.Site.Title など): サイト全体で共通するデータ
  • 関数・制御構文 (range, if など): データの加工や繰り返し処理

「この変数はFront Matterのあの部分に対応しているんだな」 と機能から関連付けて直感的にイメージできるようになれば、あなたはもうHugoマスターへの第一歩を踏み出しています！👍