2025年の最強静的ブログフレームワーク Hugo 詳細解説

Posted at 2025-02-25

Leapcell: The Next - Gen Serverless Platform for Web Hosting, Async Tasks, and Redis

Hugoの一般的な使用技術の紹介

HugoはオープンソースのgoldmarkをMarkdownパーサとして使用しており、GitHubと互換性があります。

紹介

HugoはGolangで書かれた静的ウェブサイトページ生成ツールであり、その効率はRubyで書かれたJekyllよりもはるかに高いです。Githubから直接バイナリパッケージをダウンロードし、解凍した後、PATH環境変数に追加して使用することができます。

hugo - extendedバージョンのインストールをおすすめします。これはSCSS機能をサポートしており、テーマ開発に適しています。また、goldmarkを通じて多くの拡張機能が実装されており、最も一般的に使用されるのはタスクリストです。詳細なリストについては、MarkdownGuideの紹介を参照することができます。Hugoは高度にカスタマイズ可能であり、設計時にはMarkdown構文と互換性を持つように努めています。

基本的な使用方法

テーマを通じてページをカスタマイズする: 多数のテーマが選択でき、themes.gohugo.ioで閲覧することができます。hugo - geekdocを例にとります。ダウンロードした後、直接プロジェクトのthemesディレクトリに配置します。
インストールが成功したかを確認する:

hugo version

現在のディレクトリで新しいプロジェクトを作成する:

hugo new site hugo

テーマテンプレートをthemesディレクトリに追加し、設定ファイルconfig.tomlにtheme="doks"を追加する、または--theme hydeパラメータで起動する:

git clone --depth 1 --recursive https://github.com/h - enk/doks.git themes

記事を作成する:

hugo --verbose new post/create - hugo - blog.md

サービスを起動する:

hugo server --buildDrafts --bind="0.0.0.0" --port=38787

静的ファイル（下書きを含む）を生成し、buildDirディレクトリに保存する（デフォルトではpublic）:

hugo -D

設定ファイル

デフォルトでは、ルートディレクトリのhugo.toml、hugo.yaml、hugo.jsonなどの設定ファイルが使用されます。また、--config a.toml,b.tomlのように設定ファイルを指定することもできます。ただし、ディレクトリを使用することをおすすめします。デフォルトではconfigディレクトリであり、設定ファイルのconfigDir設定項目を使用して変更することができます。

hugo.toml
config/
 |-_default/ 
 | |-hugo.toml
 | |-languages.toml
 | |-menus.en.toml
 | |-menus.cn.toml
 | `-params.toml
 |-develop/
 | |-hugo.toml
 | `-params.toml
 `-production/
   `-hugo.toml

ディレクトリの最初のレイヤーは環境であり、_defaultのデフォルト設定が含まれており、一般的にproductionディレクトリも設定されます。例えば、--environment productionで起動するとき、_defaultの設定とproductionの設定がマージされ、以下のようにテンプレートで確認することができます：

{{ if eq hugo.Environment "production" }}
<div> 本番モード </div>
{{ else }}
<div> 開発モード </div>
{{ end }}

2番目のレイヤーは設定項目のトップレベルに対応しています。一般的に、[Params]はparams.tomlに対応し、[Menu]はmenu.tomlに対応し、異なる言語も含まれています。

基本的な概念

セクション

contentディレクトリ構造に基づいて定義されるページのコレクションです。このディレクトリの下の1階層目のサブディレクトリはすべてセクションです。サブディレクトリをセクションにする場合は、そのディレクトリ内に_index.mdファイルを定義する必要があり、このようにしてすべてのセクションがセクションツリーを形成します。

content/
 `-blog/               <-- セクション、contentのサブディレクトリであるため
   |-funny - cats/
   | |-mypost.md
   | `-kittens/        <-- セクション、_index.mdを含んでいるため
   |   `-_index.md
   `-tech/             <-- セクション、上と同じ
       `-_index.md

セクションを通じてコンテンツを分類するほか、Typeのカスタマイズも許可されています。ページにTypeがない場合、セクションに対応する値がデフォルトで使用されます。使用するときは、以下の検索順序を参照することができます。テンプレートのTypeがセクションよりも優先度が高く、より良いカスタマイズが可能であることがわかります。また、異なるページタイプ、すなわちpage、section、term、home、taxonomyなど、すなわち.Kind変数を処理することができます。公式のMethods Kindの紹介を参照することができます。

テンプレート

HugoはGoLangのhtml/templateライブラリをテンプレートエンジンとして使用しており、以下の3種類のテンプレートに分類されます：

single: 単一のページをレンダリングするために使用されます。
list: 関連するコンテンツのセットをレンダリングします。たとえば、ディレクトリ内のすべてのコンテンツなどです。
partial: 他のテンプレートによって参照されることができ、テンプレートレベルのコンポーネントとして機能します。たとえば、ページヘッダーやページフッターなどです。

このうち、baseof.htmlは異なるセクションのルートテンプレートとして機能し、テンプレート検索メカニズムがあります。完全に一致するコンテンツのテンプレートが見つからない場合、1レベル上に移動してそこから検索します。基本テンプレートbaseof.htmlの検索規則は以下の通りです：

/layouts/section/-baseof.html
/themes//layouts/section/-baseof.html <--- 異なるTypeのテンプレート
/layouts//baseof.html
/themes//layouts//baseof.html
/layouts/section/baseof.html
/themes//layouts/section/baseof.html <--- 異なるセクションのテンプレート
/layouts/_default/-baseof.html
/themes//layouts/_default/-baseof.html
/layouts/_default/baseof.html
/themes//layouts/_default/baseof.html <--- デフォルト値

テンプレートでは、{{ partial "xx" . }}を通じてPartialsモジュールを導入し、モジュール内の対応するページ情報は{{ . }}を通じて閲覧することができます。また、以下のようにパラメータを追加することもできます：{{ partial "header.html" (dict "current" . "param1" "1" "param2" "2" ) }}。

上記のPartialsの導入方法のほか、{{ define "main" }} ... {{ end }}を通じて異なるタイプ（たとえばsingle、listなど）でモジュールをカスタマイズし、その後{{ block "main" . }} ... {{ end }}の方法で使用することもできます。

変数参照

テンプレートでは、{{ xxx }}の方法で変数を参照します。変数の使用方法は以下の通りです：

グローバル設定: たとえば、.Site.Params.titileはhugo.tomlの[Params]またはconfig/_default/params.tomlの設定に対応します。
ページパラメータ: 最初に指定することができ、.Params.xxxの方法で参照することができます。
その他のパラメータ: いくつかの組み込みパラメータが含まれており、直接使用することができます。たとえば、.Title、.Section、.Content、.Pageなどです。
ローカライズパラメータ: 一般的に、i18n "global - identifier"で指定するか、i18n .Site.Params.xxxで変換します。
関数の使用: たとえば、hugo.Environment、hugo.IsExtendedなどです。その他の関数については、Functionsの内容を参照することができます。

上記の変数のほか、json、yaml、toml、xmlなどの形式のデータファイルをdataディレクトリに保存し、テンプレートで.Site.Data.xxxの方法で参照することもできます。

基本構文

テンプレートは{{ }}で囲まれており、その中のコンテンツをアクション（Action）と呼びます。一般的には以下の2種類があります：

データ評価: 直接テンプレートに出力されます。直接変数を使用することも含まれます。
制御構造: 条件、ループ、関数などが含まれます。

また、各行を改行するかどうかを制御することができます。-で制御されます。たとえば、{{- -}}は開始も終了も改行しないことを意味しますが、終了時に圧縮することもできます。

----- コメント
{{/* コメント */}}
----- 既存の変数、カスタム変数へのアクセス
{{ .Title }}
{{ $var }}
{{ $var := "Value" }}
{{ $var := `Hello
World` }}

スライス VS. マップ

スライスは配列に対応しており、一般的な操作は以下の通りです：

{{ $fruit := slice "Apple" "Banana" }}

{{ $fruit = append "Cherry" $fruit }}
{{ $fruit = append $fruit (slice "Pear") }}
{{ $fruit = append (slice "Cherry" "Peach") $fruit }}

{{ $fruit = uniq $fruit }}

{{ range $fruit }}
  I love {{ . }}
{{ end }}

{{ range $index, $value := $fruit }}
  {{ $value }} or {{ . }} is at index {{ $index }}
{{ end }}

{{ $first := first 2 $fruit }}
{{ $last := last 3 $fruit }}
{{ $third := first 3 $fruit | last 1 }}
{{ $third := index $fruit 2 }}

辞書の使用方法は以下の通りです：

{{ $hero := dict "firstame" "John" "lastname" "Lennon" }}

{{ $hero = merge $hero (dict "birth" "1940") }}

{{ $hero.firstame }}
{{ $firstname := index $hero "firstname" }}
{{ range $key, $value := $hero }}
  {{ $key }}: {{ $value }}
{{ end }}

{{ $basis := "lastname" }}
{{ if eq $relation "friend" }}
  {{ $basis = "firstname" }}
{{ end }}
Hello {{ index $hero $basis }}!

{{ range slice "firstname" "lastname" }}
  {{ . }}: {{ index $hero . }}
{{ end }}

使用するときは、{{ if reflect.IsSlice $value }}またはIsMapを通じて特定のタイプを判断することができます。

論理判断

if文は特定の値の真偽を判断するために使用されますが、withを使用することをおすすめします。このとき、コンテキストはそのスコープ内で再バインドされます。

{{ if .IsHome }} xxx {{ end }}          // IsHomeが真のときに呼び出されます、それ以外の場合はnotを使用します
{{ if eq .Title "Home" }} xxx {{ end }} // 変数が等しいかどうかを判断します、neは等しくないことを表します
{{ if and .IsHome .Params.show }} xxx {{ end }}   // 複数の条件が同時に満たされる場合、orはいずれかの条件が満たされる場合
{{ if strings.Contains "hugo" "go" }} xxx {{end}} // 指定された文字列が含まれているかどうかを判断します

// 以下の2つの方法は同等であり、空の場合はスキップされます
{{ if isset .Params "title" }}
    <h4>{{ index .Params "title" }}</h4>
{{ end }}
```go
{{ with .Params.title }}
    <h4>{{ . }}</h4>
{{ end }}

// しかしifはelse if文を使用できます
{{ if (isset .Params "description") }}
    {{ index .Params "description" }}
{{ else if (isset .Params "summary") }}
    {{ index .Params "summary" }}
{{ else }}
    {{ .Summary }}
{{ end }}

// 以下はやや複雑なロジックです
{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
    <div class="caption {{ index .Params "attr" }}">
        {{ if (isset .Params "title") }}
            <h4>{{ index .Params "title" }}</h4>
        {{ end }}
        {{ if (isset .Params "caption") }}
            <p>{{ index .Params "caption" }}</p>
        {{ end }}
    </div>
{{ end }}

Paramにdescription属性が設定されている場合、Paramのdescriptionコンテンツが出力され、それ以外の場合はSummaryのコンテンツが出力されます。

{{ with .Param "description" }}
    {{ . }}
{{ else }}
    {{ .Summary }}
{{ end }}

反復

辞書データの場合、{{ range $idx, $var := .Site.Data.xxx }}を通じて反復処理することができ、配列の場合は{{ range $arr }}の方法で反復処理することができます。また、上記のDataを例にとると、以下のようにソート、フィルタリング、データの取得を行うことができます。

// ここでは、コンテキストが配列要素にアクセスします。グローバルコンテキストにアクセスするには、$.を使用してアクセスする必要があります
{{ range $array }}
    {{ . }}
{{ end }}

// 変数と要素インデックスを宣言することができます
{{ range $val := $array }}
    {{ $val }}
{{ end }}
{{ range $idx, $val := $array }}
   {{ $idx }} -- {{ $val }}
{{ end }}

// マップ要素のインデックスと値の変数を宣言する
{{ range $key, $val := $map }}
   {{ $key }} -- {{ $val }}
{{ end }}

// 渡されたパラメータが空の場合、else文が実行されます
{{ range $array }}
    {{ . }}
{{else}}
    // $arrayが空のときのみ実行されます
{{ end }}

また、以下の方法も使用できます：

<ul>
  {{ range sort .Site.Data.books.fiction "title" }}
    <li>{{ .title }} ({{ .author }})</li>
  {{ end }}
</ul>

{{ range where .Site.Data.books.fiction "isbn" "978 - 0140443530" }}
  <li>{{ .title }} ({{ .author }})</li>
{{ end }}

{{ index .Site.Data.books "historical - fiction" }}

このように、異なる変数に基づいてフィルタリングすることができ、.Site.Pagesなどの組み込み変数についても同じことができます。

以下は条件フィルタリングの処理です：

{{- if and (isset .Params "math") (eq .Params.math true) }}
{{- end -}}

ページのフィルタリング

以下は、最初に現在のセクションのデータをフィルタリングし、ページにはclass: "page"オプションを設定する必要があります。まず、年ごとに集計し、次に日付で降順にソートし、日付と対応するタイトル情報を表示します。

{{ $blogs := where (where .Site.Pages "Section" .Section) "Params.Class" "==" "page" -}}
{{ range $blogs.GroupByDate "2006" "desc" }}
<h1>{{ .Key }}</h1>
<ul>
{{ range .Pages.ByDate.Reverse }}
  <li><span>{{ .Date.Format "2006 - 01 - 02" }}</span> <a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}

ページ上の利用可能な変数は、Page Variablesを通じて閲覧することができ、{{ . }}を通じて直接印刷すると、ファイルパスが表示されます。

その他の一般的な使用例は以下の通りです：

{{ range .Data.Pages }}                        // Data.Pagesを反復処理
{{ range where .Data.Pages "Section" "blog" }} // Data.Pagesを反復処理し、Sectionがblogのデータをフィルタリング
{{ range first 10 .Data.Pages }}               // Data.Pagesを反復処理し、最初の10件のデータを取得
{{ range last 10 .Data.Pages }}                // Data.Pagesを反復処理し、最後の10件のデータを取得
{{ range after 10 .Data.Pages }}               // Data.Pagesを反復処理し、10番目以降のデータを取得
{{ range until 10 .Data.Pages }}               // Data.Pagesを反復処理し、10番目までのデータを取得

ショートコード

ショートコードは主に、Markdownで表現しにくい処理ロジックを処理するために使用され、元のhtmlコードの一部の記述を省略することができます。公式ではいくつかのデフォルトの実装が提供されており、たとえばいくつかのビデオサイトへのリンク、relrefなどです。ソースコードはGithubで参照することができます。

foobarというショートコードがあるとします。以下のように使用することができます。パラメータの囲い方に注意してください。現在、レンダリングを防ぐより良い方法は見つかっていません。

{{ foobar "foo" "bar" }}
Some short codes
{{ /foobar }}

上記のパラメータをショートコードテンプレートで取得する方法はいくつかあります：with .Get 0を通じて取得する方法は最も単純で直接的です。または、index .Params 0を通じて取得することもでき、その中のコンテンツは.Innerメソッドを通じて読み取ることができ、呼び出す必要があります。また、Hugo ShortCodesのいくつかの例を参照することもできます。

一般的に使用される関数

テンプレートでは、{{ with .Site.Data.Resume . }} {{ .SomeData }} {{ end }}の方法で参照することができます。

高度な使用方法

静的ファイル

画像、CSS、JavaScriptなどを含み、一般的に既存のファイルです。たとえば、サードパーティライブラリのBootstrap、FontAwesomeなどです。参照するときは、staticディレクトリに配置する必要があり、テンプレートでは対応するディレクトリに配置し、自動的にコピーされます。

{{ "css/bootstrap.min.css" | absURL }}の方法で参照することができます。このとき、http://foobar.com/css/bootstrap.min.cssにアクセスすると、static/css/bootstrap.min.cssファイルにマッピングされます。

マウント

npmを通じてサードパーティのJSパッケージを管理することができますが、このときは設定ファイルのmodule.mountsを通じて設定する必要があります。

[module]
  [[module.mounts]]    
    source = "node_modules/katex/dist"
    target = "static/katex"

その後、テンプレートでは以下のように使用することができます：

<script type="text/javascript" src="{{ "katex/katex.min.js" | absURL }}"></script>`
<link rel="stylesheet" href="{{ "katex/katex.min.css" | absURL }}"/>

CSS

0.43バージョン以降、HugoはSASSのコンパイルをサポートしています。ただし、ソースファイルは/assets/scss/または/themes//assets/scss/ディレクトリにのみ配置することができます。その後、以下のように導入することができます：

{{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
  <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}

resources.Getを使用してSCSSファイルのコンテンツを取得し、その後パイプラインを使用してコンパイル、圧縮、指紋を生成します。これにより、生成されたファイルにハッシュファイル名を付けることができ、CDNから最新のCSSを取得できるようになり、キャッシュされた古いファイルを取得することがなくなります。また、上記のCSSをコンパイルするための設定オプションのほか、以下のものも参照することができます：

{{ $opts := (dict "outputStyle" "compressed" "enableSourceMap" true "includePaths" (slice "node_modules")) -}}

以下のコマンドを通じてコードのハイライトを生成することができ、Style LongerとStyleの例を参照することができます。

hugo gen chromastyles --style=monokai > syntax.css

設定パラメータcodeFences=trueを設定する必要があります。そうしないと、行番号などの情報がテーブル形式で表示され、表示が異常になります。

JavaScript

CSSと同様に、JSスクリプトは以下のように導入することができます：

{{ $params := dict "api" "https://example.org/api" }}
{{ with resources.Get "js/main.js" }}
  {{ if hugo.IsDevelopment }}
    {{ with . | js.Build }}
      <script src="{{ .RelPermalink }}"></script>
    {{ end }}
  {{ else }}
    {{ $opts := dict "minify" true "params" $params }}
    {{ with . | js.Build $opts | fingerprint }}
      <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
    {{ end }}
  {{ end }}
{{ end }}

スクリプトでは、import * as params from '@params';の方法でパラメータを参照することができ、Shimsメソッドを通じてReactコードを導入することすらできます。より多くの機能については、Hugo JSを参照することができます。

画像のレンダリング

Hugoで画像形式をカスタマイズするのは少し面倒です。![name](uri){: width="420"}のような方法はサポートされていません。htmlを直接使用できるため、以下のように設定することができます：

<img src="picture.png" alt="some message" width="50%" />

cssでimgの配置をカスタマイズすることができますが、このときは1つの配置のみを使用することができます。また、公式ではfigureのショートコードが提供されており、使用することができますが、異なるプラットフォームで互換性の問題が発生する場合があります。

もう1つの方法は、layouts/_default/_markup/render - image.htmlで画像のレンダリング方法をカスタマイズし、その後![name](uri?width=100px)のように使用することです。ただし、サポートされるパラメータは上記のファイルで設定する必要があります。

その他のレンダリングフックについては、Render Hooksの内容を参照することができます。

データ転送

データをScratchを通じて転送することができ、これはPageとShortCodesの間でデータを転送するために使用されます。テンプレートで一時的なデータ転送を行いたい場合は、newScratchを通じて新しいものを作成することができます。以下はHugoが自動的に生成するScratchを例にとります。.Page.Scratchと.Scratchは同じ機能を持っています：

{{ .Scratch.Set "hey" "Hello" }} # 3や(slice "Hello" "World")でもよい
{{ .Scratch.Get "hey" }}         # 取得
{{ .Scratch.Add "hey" "Welcome" }} # 加算を行い、Go言語と同様に、文字列の連結、数値の加算、配列の連結
{{ .Scratch.GetSortedMapValues "hey" }} # Getを通じてマップを取得するほか、キーでソートされた値を返すこともできます
{{ .Scratch.Delete "hey" }}      # 削除

{{ .Scratch.SetInMap "hey" "Hello" "World" }} # マップを設定し、key:valueがHello:Worldに対応
{{ .Scratch.SetInMap "hey" "Hey" "Andy" }}
{{ .Scratch.Get "hey" }} # map[Hello:World Hey:Andy]

テンプレートのデバッグ

{{ printf "%#v" .Permalink }}を通じて現在の変数情報を印刷することができます。また、ページレイアウトをデバッグしたい場合は、<head>に以下のコンテンツを追加して、簡単に確認する

<style> 
div { 
  border: 1px solid black;
  background-color: LightSkyBlue; 
} 
</style>

Hugoはデフォルトで関連記事のための関連コンテンツ設定を提供しており、デフォルトではキーワード、日付、タグを通じて関連性をマッチングします。

ベストプラクティス

トップレベルのディレクトリには archetypes、assets、content、data、i18n、static、layouts のいくつかのディレクトリが含まれています：

archetypes/: new サブコマンドで新しい記事を作成する際のテンプレートです。
config/: デフォルトでは hugo.[toml|yaml|json] が設定として使用され、以下のディレクトリ方式を使用することもできます：
- _default/: デフォルト設定です。
- production/: グローバル設定です。
i18n/: ローカライズ用です。
themes/:
- halo/: 対応するテンプレート名です。
  - assets/: テンプレート内のリソースファイルです。
    - images/
    - js/: JavaScript関連のスクリプトで、詳細は footer/script - footer.html を参照してください。
    - scss/: SCSSファイルです。
      - app.scss: トップレベルのSCSSファイルで、他のディレクトリのファイルをインクルードします。詳細は head/head.html を参照してください。
    - static/: 静的ファイルです。
      - syntax.css: 上記の hugo gen chromastyles コマンドで生成されたCSSファイルで、詳細は head/head.html を参照してください。
  - layouts/: レイアウトテンプレートで、_default はデフォルトで、partials は異なるテンプレートの参照です。
    - _default/
    - blog/: blogセクションのテンプレートに対応しています。
    - docs/: docsセクションのテンプレートに対応しています。
    - partials/: 異なるテンプレート内の参照です。
    - resume/: resumeセクションのテンプレートに対応しています。
      - baseof.html: レンダリング用のルートページです。
    - shortcodes/: ショートコードです。
    - slide/: slideセクションのテンプレートに対応しています。
    - 404.html: 404ページを生成します。

CSS関連のコンテンツは以下のファイルに依存しています：

syntax.css: 構文ハイライト用で、圧縮するだけです。
main.css: コアのカスタム設定です。bootstrap変数を使用するため、scssテンプレートでも参照されます。したがって、bootstrap.min.css を個別に導入する必要はありません。
fontawesome.min.css: 使用するアイコンで、詳細は Icons の内容を参照してください。

また、Bootstrapの関連変数は bootstrap/scss/_variables.scss に保存されています。