データテンプレート
Hugo の組み込み変数に加えて、ローカルとダイナミック両方のソースから取得する、テンプレートやショートコードで独自のカスタムデータを指定できます。
Hugo は、Hugo プロジェクトのルートにある data ディレクトリにある YAML、JSON、XML、TOML ファイルからデータを読み込むことをサポートしています。
データフォルダー
data フォルダには、Hugo がサイトを生成する際に使用する追加データを保存しておく必要があります。
データファイルは独立したページを生成するためのものではありません。 データファイルは、以下のような方法でコンテンツファイルを補完する必要があります。
- フロントマター・フィールドが制御不能になったときにコンテンツを拡張する。
- テンプレートでより大きなデータセットを表示する (下の例を参照)。
どちらの場合も、(独自の) ファイル内のデータをアウトソースすることをお勧めします。
これらのファイルは、YAML、JSON、XML、または TOML ファイル (拡張子は .yml、.yaml、.json、.xml、.toml) である必要があります。データは .Site.Data 変数内の map としてアクセスできます。
.site.Data.filename 表記を使用してデータにアクセスする場合、ファイル名はアンダースコアまたは Unicode 文字で始まり、その後に 0 個以上のアンダースコア、Unicode 文字、または Unicode 数字が続く必要があります。 たとえば、以下のようになります。
123.json- 無効x123.json- 有効_123.json- 有効
index
関数を使用してデータにアクセスする場合、ファイル名は関係ありません。 たとえば、以下のようになります。
| データファイル | テンプレート コード |
|---|---|
123.json |
{{ index .Site.Data "123" }} |
x123.json |
{{ index .Site.Data "x123" }} |
_123.json |
{{ index .Site.Data "_123" }} |
x-123.json |
{{ index .Site.Data "x-123" }} |
テーマ内のデータファイル
データファイルは [Hugo テーマ][themes] でも使用できます。
ただし、テーマ データファイルはプロジェクト ディレクトリに優先してマージされることに注意してください。 つまり、同じ名前と相対パスを持つ 2 つのファイルがある場合、ルートプロジェクトの data ディレクトリにあるファイルのデータが、themes/<THEME>/data ディレクトリにあるファイルのデータよりも優先されます。
したがって、テーマの作成者は、ユーザーが テーマをカスタマイズする
と決めたときに、簡単に上書きされてしまうようなデータファイルを含まないように注意する必要があります。オーバーライドされて困るテーマ固有のデータ項目については、フォルダー構造のプレフィックスに名前空間を付けるのが賢明です。たとえば mytheme/data/<THEME>/somekey/... といった具合です。このような重複があるかどうかを調べるには、-v フラグを付けて hugo を実行します。
データファイルからデータテンプレートを使って作成したマップ内のキーは、ファイル中の path、filename、key (該当する場合) のドット連結したセットになります。
これは、例を挙げて説明するのが一番わかりやすいです。
例: Jaco Pastorius のソロ ディスコグラフィー
Jaco Pastorius は素晴らしいベーシストでしたが、彼のソロディスコグラフィーは例として挙げるには短いものです。 John Patitucci もベースの巨人です。
以下の例は少し不自然ですが、データファイルの柔軟性を示しています。 この例では、ファイル形式として TOML を使用し、以下の 2 つのデータファイルを使用します。
data/jazz/bass/jacopastorius.tomldata/jazz/bass/johnpatitucci.toml
jacopastorius.toml には以下の内容が含まれています。 johnpatitucci.toml にも同様のリストが含まれています。
ベーシストのリストは .Site.Data.jazz.bass でアクセスでき、単一のベーシストはファイル名をサフィックスなしで (たとえば、.Site.Data.jazz.bass.jacopastorius) 追加します。
以下のテンプレート内で、すべてのベーシストの録音リストをレンダリングできるようになりました。
{{ range $.Site.Data.jazz.bass }}
{{ partial "artist.html" . }}
{{ end }}
そして、partials/artist.html の中に、以下のコードがあるとします。
<ul>
{{ range .discography }}
<li>{{ . }}</li>
{{ end }}
</ul>
新しいお気に入りのベーシストを発見しましたか? 同じディレクトリに別の .toml ファイルを追加するだけです。
例: データファイルの名前付き値にアクセスする
data/ に直接置かれている User0123.[yml|toml|xml|json] データファイルに、以下のデータ構造があると仮定します。
以下のコードを使用して、レイアウトに Short Description をレンダリングできます。
<div>Short Description of {{ .Site.Data.User0123.Name }}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
markdownify テンプレート関数
を使用していることに注意してください。これは Markdown レンダリングエンジンを通して説明を送信します。
リモートデータを取得する
リモートデータを取得するには、以下のように getJSON または getCSV を使用します。
{{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }}
URL にプレフィックスまたはポストフィックスを使用した場合、関数は 可変長引数 を受け付けます。
{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }}
getCSV のセパレーターは最初の位置に配置する必要があり、1 文字の長さにする必要があります。
渡されたすべての引数は、以下のように、最終的な URL に結合されます。
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
上記は、内部的には以下のように解決されます。
{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }}
HTTP ヘッダーを追加する
getJSON と getCSV のどちらも、最後の引数としてオプションのマップを受け取ります。たとえば、以下のようになります。
{{ $data := getJSON "https://example.org/api" (dict "Authorization" "Bearer abcd") }}
同じヘッダーキーに複数の値が必要な場合は、以下のようにスライスを使用します。
{{ $data := getJSON "https://example.org/api" (dict "X-List" (slice "a" "b" "c")) }}
CSV ファイルの例
getCSV の場合、最初の位置に 1 文字長のセパレーターを配置し、その後に URL を配置する必要があります。 以下は、公開された CSV から パーシャル
で HTML テーブルを作成する例です。
<table>
<thead>
<tr>
<th>Name</th>
<th>Position</th>
<th>Salary</th>
</tr>
</thead>
<tbody>
{{ $url := "https://example.com/finance/employee-salaries.csv" }}
{{ $sep := "," }}
{{ range $i, $r := getCSV $sep $url }}
<tr>
<td>{{ index $r 0 }}</td>
<td>{{ index $r 1 }}</td>
<td>{{ index $r 2 }}</td>
</tr>
{{ end }}
</tbody>
</table>現在の行から n 番目の列を出力するには、式 {{ index $r number }} を使用する必要があります。
キャッシュ URL
ダウンロードされた各 URL は、デフォルトフォルダー $TMPDIR/hugo_cache_$USER/ にキャッシュされます。 変数 $TMPDIR は、システム依存の一時ディレクトリに解決されます。
コマンドラインフラグ --cacheDir を使用すると、システム上の任意のフォルダをキャッシュ ディレクトリとして指定することができます。
また、メイン設定ファイル
で cacheDir を設定することができます。
キャッシュがまったく気に入らない場合は、コマンドラインフラグ --ignoreCache を使用してキャッシュを完全に無効にできます。
REST URL 使用時の認証
現状では、URL に入れることができる認証方法のみ使用可能です。 OAuth などの認証方式は実装されていません。
ローカルファイルをロードする
getJSON と getCSV でローカルファイルをロードするには、ソースファイルが Hugo の作業ディレクトリ内に存在する必要があります。ファイルの拡張子は関係ありませんが、コンテンツは重要です。
上記の 「リモートデータを取得する」 と同じ出力ロジックを適用します。
getCSV を使用してロードされるローカル CSV ファイルは、data ディレクトリの 外 に配置する必要があります。
データファイルを使用した LiveReload
URL のコンテンツが変更されたときに LiveReload
をトリガーする機会はありません。しかし、ローカル ファイル (すなわち、data/* と themes/<THEME>/data/*) が変更されると、LiveReload がトリガーされることになります。シンボリックリンクはサポートされていません。また、データのダウンロードには時間がかかるため、Hugo はデータのダウンロードが完了するまで Markdown ファイルの処理を停止することにも注意してください。
データ駆動型コンテンツの例
- フォトギャラリー JSON 搭載: https://github.com/pcdummy/hugo-lightslider-example
- カスタムショートコード でデータ駆動型コンテンツを使用した、 投稿における スター付きの GitHub リポジトリ