Hugoメモ

静的サイトジェネレータHugoに関するメモです。基本的に公式ドキュメントから抜粋しています。

設定ファイル

主要な設定項目

config.tomlの主要項目をAll configuration settingsより抜粋。テーマによっては指定しても意味がない場合があるので注意。

設定項目	説明	例
baseURL	公開サイトの絶対URL。末尾は'	https://example.com
contentDir	コンテンツを配置するディレクトリ	省略時はcontent
defaultContentLanguage	デフォルトの言語	省略時はen
enableGitInfo	trueにすると各ページの最終更新日時(Lastmod)がgit commitした日時になる	省略時はfalse
googleAnalytics	Google AnalyticsのトラッキングID	省略時は""
hasCJKLanguage	日本語・韓国語・中国語を前提として.Summaryと.WordCountの値を調整	省略時はfalse
paginate	ページネーションする場合の1ページあたりのコンテンツ数	省略時は10
publishDir	最終的な静的ファイルを書き込むディレクトリ	省略時はpublic
rssLimit	RSSフィードの最大アイテム数	省略時は-1(全て)
summaryLength	本文を要約表示する場合の文字数	省略時は70
taxonomies	タクソノミーを指定する	省略時はtagとcategory
theme	使用するテーマ
timeZone	タイムゾーン。FrontMatterの日付を解析するために使われる	JP/Japan
title	サイトのタイトル
[Params]	サイト固有の設定値を入れ子で記述する。テンプレートから.Site.Paramsで参照
permalinks	サイト構成で各トップレベルセクションのURLパターンを定義する	後述

記述例

baseURL = 'https://yoursite.example.com/'
title = 'My Hugo Site'
theme = "sample"
[params]
  AuthorName = 'TAKEUCHI Hitoshi'
  GitHubUser = 'htakeuchi'
  ListOfFoo = ['foo1', 'foo2']
  SidebarRecentLimit = 5
  Subtitle = 'Hugo is Absurdly Fast!'
[permalinks]
  posts = '/:year/:month/:title/'

permalinksの設定

サイト構成で、各トップレベル セクションのURLパターンを定義する。各URLパターンは、特定の言語やページの種類をターゲットにできる。ページのFrontMatterの値でオーバーライドすることもできる。

コンテンツ構成の例

content/
├── posts/
│   ├── bash-in-slow-motion.md
│   └── tls-in-a-nutshell.md
├── tutorials/
│   ├── git-for-beginners.md
│   └── javascript-bundling-with-hugo.md
└── _index.md

config.tomlの例

[permalinks]
  [permalinks.page]
    posts = '/articles/:year/:month/:slug/'
    tutorials = '/training/:slug/'
  [permalinks.section]
    posts = '/articles/'
    tutorials = '/training/'

公開されるサイト構造の例

public/
├── articles/
│   ├── 2023/
│   │   ├── 04/
│   │   │   └── bash-in-slow-motion/
│   │   │       └── index.html
│   │   └── 06/
│   │       └── tls-in-a-nutshell/
│   │           └── index.html
│   └── index.html
├── training/
│   ├── git-for-beginners/
│   │   └── index.html
│   ├── javascript-bundling-with-hugo/
│   │   └── index.html
│   └── index.html
└── index.html

タクソノミーの設定

コンテンツをグルーピングするための項目名。「タグ」や「カテゴリー」といった分類名をタクソノミーとよぶ。デフォルトでtagsとcategoriesというタクソノミーが定義されている。これらの分類のみで良い場合は特に設定は不要。

コンテンツのタクソノミーの設定

各コンテンツのタクソノミーを指定する場合、FrontMatterで以下のように指定する。

+++
title = 'Hugo: A fast and flexible static site generator'
categories = ['Development']
tags = ['Development', 'Go', 'fast', 'Blogging']
+++

目次の設定

目次を出力する場合、config.tomlでオプションを指定できる。

[markup]
  [markup.tableOfContents]
    startLevel = 2
    endLevel = 3
    ordered = false

startLevel

ヘディングのレベル。1を指定すればh1から開始

endLevel

目次にする最も深い階層

ordered

順序付きリストにするか

変数

サイト変数

Site variables | Hugoより抜粋

これらの変数はグローバル変数のため、全テンプレートから参照可能。

変数	説明
.Site.BaseURL	config.tomlで定義したサイトのベースURL
.Site.GoogleAnalytics	config.tomlで定義したGoogle Analyticsのトラッキングコード
.Site.Home	ホームページのページオブジェクトへの参照
.Site.BaseURL	ローカル環境で実行されている場合にtrueになる
.Site.Pages	全コンテンツを日付順にソートした破裂
.Site.Taxonomies	config.tomlで定義したタクソノミー
.Site.Title	config.tomlで定義したサイトのタイトル
.Site.Params	config.tomlの[params]セクションで定義した値。

.Site.Paramsの使用例

config.toml

baseURL = 'https://yoursite.example.com/'
[params]
  author = 'Nikola Tesla'
  description = "Tesla's Awesome Hugo Site"

テンプレートでの参照例

<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" />

ページ変数

Page variables | Hugoより抜粋

変数	説明
.Content	コンテンツ。FrontMatterは省かれる
.Date	FrontMatterで指定した日付
.Description	FrontMatterで指定した説明文
.Kind	ページの種類。page,home,section,taxonomy,termのいずれか
.Lastmod	ファイルの最終更新日。.GitInfoが無効な場合.Dateと同じ
.Permalink	このページのパーマリンク
.PlainWords	ページの内容からHTMLを取り除いたもの
.RawContent	生のマークダウン
.Site	サイト変数への参照
.Summary	コンテンツの要約
.TableOfContents	レンダリングされたページの目次
.Title	このページのタイトル
.Truncated	.Summaryで切り捨てられた場合はtrue
.Type	このページの種類。FrontMatterで指定していない場合は、第一階層のディレクトリ名

ページメソッド

Pages methods | Hugoを抜粋

変数	説明
.Next	引数として送られたページから相対的に次のページを指す
.Prev	引数として送られたページから相対的に前のページを指す

タクソノミー変数

Taxonomy variables | Hugo

変数	説明
.Data.Pages	このタクソノミーに関連する用語ページのコレクション
.Date	FrontMatterで指定した日付

テンプレート

Templating | Hugo

Hugoのテンプレートはgolangのhtml/templateとtext/templateをベースにしている。

• template package - text/template - Go Packages

{{と}}の中に書くアクション以外はそのまま出力される。

アクション

コメント

{{/* コメント */}}

スペースをトリミングする

{{- /* 前後のスペースをトリミングして出力 */ -}}

パイプライン

{{パイプライン}}

パイプラインの値のデフォルトのテキスト表現（fmt.Printで出力されるものと同じ）が出力にコピーされる。

条件分岐(if)

{{if pipeline}} T1 {{end}}

パイプラインの値が空の場合、出力は生成されない。空の値と評価されるのは以下のいずれか。

• false
• 0
• 任意の nil ポインタまたはインターフェイス値
• 長さ 0 の配列、スライス、マップ、文字列

ifを使った条件分岐ではdotの値に影響を与えない。

{{if pipeline}} T1 {{else}} T0 {{end}}

パイプラインの値が空でない場合T1を実行し、空の場合はT0を実行する。

{{if pipeline1}} T1 {{else if pipeline2}} T0 {{end}}

• パイプライン1の値が空でない場合T1を実行
• パイプライン1の値が空でpipeline2の値が空でない場合T0を実行

論理条件(or/and)

{{ if or
  (isset .Params "alt")
  (isset .Params "caption")
}}

複数の条件をorで評価するパターン

{{ if 
  (and 
    (or 
      (isset .Params "title") 
      (isset .Params "caption")) 
    (isset .Params "attr")) 
}}

andとorを組み合わせるパターン。1行で書くこともできる。

{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}

条件分岐(with)

{{with pipeline}} T1 {{end}}

パイプラインの値が空の場合、出力は生成されない。それ以外はdotがパイプラインの値に設定されT1が実行される。

{{with pipeline}} T1 {{else}} T0 {{end}}

• パイプラインの値が空の場合、dotは影響を受けずT0を実行する
• パイプラインの値が空でない場合、dotがパイプラインの値に設定されT1を実行する

繰り返し(range)

{{range pipeline}} T1 {{end}}

パイプラインの値が配列、スライス、マップ、チャネルのいずれかの場合に使用できる。

• パイプラインの値の長さが0の場合、何も出力されない
• そうでない場合は、ドットが配列の連続する要素に設定されT1が実行される
• 値がマップであり、キーが定義された順序を持つ基本型である場合キー順にソートされる

{{range pipeline}} T1 {{else}} T0 {{end}}

パイプラインの値の長さが0の場合dotは影響を受けずT0を実行し、長さが1以上の場合はドットが配列の連続する要素に設定されT1が実行される。

{{break}}

最も内側のrangeループを終了する。

{{continue}}

処理を中断し最も内側のループの次の要素の反復を開始する。

{{ range $elem_val := $array }}
    {{ $elem_val }}
{{ end }}

とすると、配列の要素の値が$elem_valに設定され処理の中で参照できる。

{{range $index, $element := pipeline}} T1 {{else}} T0 {{end}}

とすると、$indexには配列・スライスのインデックス、マップのキーが設定され、$elmentには要素の値が設定され処理の中で参照できる。

名前付きテンプレートの定義と参照(define/template/block)

{{define "T1"}} T1 {{end}}
{{template "T1"}}

T1という名前でテンプレートを定義する。

{{template "T1"}}

T1という名前のテンプレートを展開する。

{{template "T1" pipeline}}

T1という名前のテンプレートへパイプラインの出力を渡す。

{{define "T1"}} Hello {{.}} {{end}}
{{template "T1" "World!"}}

とすると、Hello World!が出力される。

{{block "name" pipeline}} T1 {{end}}

ブロックはテンプレートを定義するための省略記法。以下の記述と同じ意味になる。

{{define "name"}} T1 {{end}}
{{template "name" pipeline}}

ルート・テンプレートのセットを定義し、その中でブロック・テンプレートを再定義してカスタマイズする用途で使われる。

パイプラインの値が空の場合、出力は生成されない。そうでない場合、dotがパイプラインの値に設定され、T1が実行される。

変数

Hugoが提供するデータオブジェクトへアクセスする場合、

<title>{{ Page.Title }}</title>

のようにアクセスできる。HugoではPageがデフォルトのスコープのためPageを省略することができる。

<title>{{ .Title }}</title>

独自の変数を定義する場合、接頭辞として$を付ける。

{{ $address := "123 Main St." }} 
{{ $address }}

定義済みの変数を再定義する場合$を使う。

{{ $var := "Hugo Page" }}
{{ if .IsHome }}
    {{ $var = "Hugo Home" }}
{{ end }}
Var is {{ $var }}