静的サイトジェネレータ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.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 }}" />
ページ変数
変数 | 説明 |
---|---|
.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で指定していない場合は、第一階層のディレクトリ名 |
ページメソッド
変数 | 説明 |
---|---|
.Next | 引数として送られたページから相対的に次のページを指す |
.Prev | 引数として送られたページから相対的に前のページを指す |
タクソノミー変数
変数 | 説明 |
---|---|
.Data.Pages | このタクソノミーに関連する用語ページのコレクション |
.Date | FrontMatterで指定した日付 |
テンプレート
Hugoのテンプレートはgolangのhtml/template
とtext/template
をベースにしている。
{{
と}}
の中に書くアクション
以外はそのまま出力される。
アクション
コメント
{{/* コメント */}}
スペースをトリミングする
{{- /* 前後のスペースをトリミングして出力 */ -}}
パイプライン
{{パイプライン}}
パイプラインの値のデフォルトのテキスト表現(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 }}