Hugo Site Build Lifecycle

Hugo は設定、マウントされたファイル、コンテンツメタデータ、テンプレート、リソースからサイトを構築します。 ファイルの配置はページ種別、バンドル境界、テンプレート検索を決定するため、データモデルの一部です。

ビルド設定の選択 #

hugo コマンドは本番ビルドを実行し、--destination で対象を変更しない限り public/ に書き込みます。 hugo server は開発ビルドを提供し、その依存関係を監視します。

hugo --environment production
hugo server --environment development

環境の既定値は異なり、hugo は production、hugo server は development を使います。 --environment または HUGO_ENVIRONMENT で明示的な環境を選びます。プロジェクトでは hugo.toml のような単一の設定ファイル、 コンマ区切りの --config リスト、config/_default/ と config/<environment>/ 下の階層化ファイルを使えます。 後から指定した、より具体的な設定が先の設定を上書きするため、ビルド診断にはリポジトリのリビジョンだけでなくコマンドと環境を記録します。

モジュールのマウントはコンテンツ収集より前に解決されます。マウントは複数のソースディレクトリを仮想の content、assets、static、layouts ツリーへ結合できます。そのため物理的な content/ ディレクトリだけを調べると、 ビルド入力を見落とす可能性があります。

ページ、セクション、タクソノミー、リソースの分類 #

Hugo はファイル名とディレクトリ構造からページ種別を導出します。

• content/_index.md はホームページのコンテンツとメタデータを提供します。
• セクションディレクトリには _index.md を置け、それによってそのセクションのブランチバンドルが作られます。
• index.md を含むディレクトリはリーフバンドルです。その下の Markdown ファイルは独立したページではなくページリソースになります。
• その他のコンテンツファイルは、含まれているセクション内の通常ページになります。
• 設定されたタクソノミーは front matter からタクソノミーページとタームページを生成します。

ブランチバンドルには子ページとセクションを含められます。リーフバンドルは、画像、データ、生成ファイルなどのリソースを伴う 1 ページを表します。

content/
  posts/
    _index.md
    canvas/
      index.md
      diagram.svg

posts/canvas/ のページは .Page.Resources を通じて diagram.svg を解決できます。 static/ 下のファイルは別の経路をたどります。Hugo はそれらを処理可能なページやグローバルリソースとして公開せず、宛先へコピーします。

Front Matter とカスケードからのページ構築 #

Front matter は title、date、draft、outputs、layout、type、タクソノミー、カスタムパラメーターなどのフィールドを提供します。 Hugo はそれらの値を、パス、言語、サイト設定、Git メタデータから推測した既定値と組み合わせます。

サイト設定またはブランチバンドルの _index.md にある cascade は、子孫へ front matter の既定値を提供します。

cascade:
  type: docs
  params:
    audience: developers

子孫の front matter はカスケードされた値を上書きできます。カスケードではパス、ページ種別、環境、言語の対象セレクターも使えます。 結果のページオブジェクトは適用されたすべての層を反映するため、予想外の .Type や .Params の値は、 コンテンツファイルと祖先のカスケードの両方をたどって調査します。

Hugo はページ構築中に翻訳、エイリアス、ページリソース、タクソノミーターム、セクションの祖先も関連付けます。 テンプレートはファイルを個別に解析するのではなく、完成したページグラフを利用します。

コンテンツの変換と出力のレンダリング #

概念上のビルド経路は次のとおりです。

1. 設定、モジュール、データ、翻訳、テンプレート、マウントされた files.
2. セクションとタクソノミーを含むページとリソースのグラフを構築する。
3. コンテンツを解析し、ショートコードを展開し、Markdown レンダーフックを呼び出す。
4. 有効な各出力形式を対応するテンプレートでレンダリングする。
5. 要求されたアセットを処理し、レンダリング済みファイルと静的ファイルを公開する。

テンプレート評価はコンテンツやアセットの変換を遅延して要求できるため、これらのフェーズは依存関係を示すものであり、 内部 goroutine の順序を保証するものではありません。.Content の生成中にショートコードが実行され、 周囲のページテンプレートがその結果を HTML、RSS、JSON などの出力へ配置します。

出力形式はサイトとページ種別ごとに設定します。1 つのページは同じコンテンツから複数のファイルを出力できます。

outputs:
  home:
    - HTML
    - RSS
    - JSON

テンプレート検索では、ページ種別、type、セクション、レイアウト、言語、出力形式を考慮します。 HTML の単一ページレイアウトのような形式固有のテンプレートが、RSS 出力を自動的に提供するわけではありません。 予期しないフォールバックを診断する場合は、ハードコードされたファイル名を仮定せず、テンプレートメトリクスや警告を有効にして Hugo を実行します。

キャッシュと開発ビルドの考慮 #

Hugo はダウンロードしたモジュール、リモートリソース、処理済みアセットをキャッシュします。 アセットフィンガープリントによって有効なキャッシュ結果を再利用でき、テンプレートやソースの変更は依存先を無効化します。 プロジェクトが意図的にそのキャッシュを使う場合、resources/_gen/ 下の生成ファイルをコミットまたは CI で復元できますが、 それらはソースコンテンツではなく派生アーティファクトです。

hugo server は依存関係グラフをメモリに保持し、変更を監視し、高速レンダリングで対話的な開発に必要なページを再構築します。 通常は public/ のファイルを正確に再現するのではなく、メモリから提供します。 完全な開発再レンダリングが必要な場合は --disableFastRender を使い、サーバー出力をディスクで調べる場合だけ --renderToDisk を使います。

開発用キャッシュと差分レンダリングは宣言されていない依存関係を隠す可能性があるため、クリーンな本番ビルドがリリースチェックになります。

hugo --gc --cleanDestinationDir --environment production

--cleanDestinationDir は現在のビルドで Hugo が生成しない宛先内のファイルを削除し、--gc は未使用のキャッシュエントリを削除します。 どちらのオプションも誤ったコンテンツ分類やテンプレート検索を修復するものではありません。これらはプロジェクト構造と設定から決まります。