メインコンテンツにスキップ

Hugo Modules を使ってローカルのテーマをサイトに接続する方法

タグ: 🏷 hugo ,テーマ

Hugo でテーマを自作・カスタマイズする場合、Hugo Modules を使うとテーマを別リポジトリ（Gitなどで管理されるコードの保管場所）やローカルフォルダとして管理しつつ、サイトと簡単に接続できます。 この記事では、初心者の方でも分かるように「ローカルテーマとサイトを Hugo Modules で接続する手順」を解説します。

Hugo Modules とは？

Hugo Modules は、Go Modules をベースにした Hugo の依存管理機能です。これを使うと、テーマやコンポーネントを別フォルダや別リポジトリとして独立管理しながら、サイトと柔軟に接続できます。

メリット：

  • テーマとサイトを別々にバージョン管理（変更履歴を記録し、特定の時点の状態に戻したり、複数の変更を統合したりする仕組み）できる
  • テーマの変更をサイトで即時プレビューできる
  • 複数サイトで同じテーマを共有可能
  • バージョンタグ管理で安定した公開ができる

準備

必要な環境

フォルダ構成例

今回は、テーマとサイトを別フォルダにして管理します。

projects/
├─ my-hugo-theme/ ← テーマ（自作テーマのフォルダ）
└─ my-hugo-site/ ← サイト（Hugoサイト本体のフォルダ）

テーマ側の初期化

まずテーマのフォルダを作り、Hugo Modules を初期化します。これにより、テーマがHugo Modulesとして認識され、他のサイトから利用できるようになります。

cd my-hugo-theme
hugo mod init github.com/yourname/my-hugo-theme

hugo mod init コマンドは、go.mod ファイルを作成し、モジュールのパス（github.com/yourname/my-hugo-theme）を設定します。このパスは、後でサイト側からテーマをインポートする際に使用します。

theme.toml（最低限）：

name = "my-hugo-theme"
license = "MIT"
description = "My first Hugo theme"
min_version = "0.120.0"

この theme.toml ファイルは、テーマのメタデータを定義します。name はテーマの名前、min_version はこのテーマが動作するために必要なHugoの最小バージョンです。

サイト側の初期化

サイト側も Hugo Modules を初期化します。これにより、サイトがHugo Modulesを利用できるようになります。

cd ../my-hugo-site
hugo new site .
hugo mod init github.com/yourname/my-hugo-site

hugo new site . は現在のディレクトリに新しいHugoサイトを作成します。hugo mod init はサイトの go.mod ファイルを作成します。

サイトにテーマをインポート

config.toml（または hugo.toml）にモジュールのインポート設定を追加します。これにより、サイトがどのテーマモジュールを使用するかをHugoに伝えます。

baseURL = "https://example.com/"
title = "My Hugo Site"

[module]
  [[module.imports]]
    path = "github.com/yamadatt/hugo-theme-karuta"

module.imports セクションで、テーマのモジュールパス（github.com/yourname/my-hugo-theme）を指定します。Hugoはこのパスを元にテーマを探しに行きます。

ローカルのテーマを接続する

開発中は、リモートリポジトリではなくローカルのテーマフォルダを直接参照させたい場合があります。これには2つの方法があります。

方法1: go mod edit -replace を使う

この方法は、Go Modulesの機能を使って、特定のモジュールパスをローカルのパスに置き換えるものです。これにより、Hugoはリモートのテーマではなく、指定したローカルフォルダのテーマを使用するようになります。

cd my-hugo-site
go mod edit -replace=github.com/yamadatt/hugo-theme-karuta=../hugo-theme-karuta/themes/karuta
hugo mod tidy
  • go mod edit -replace=...: go.mod ファイルに置き換えルールを追加します。
  • hugo mod tidy: 依存関係を整理し、必要なモジュールをダウンロードします。この時、置き換えルールが適用されます。

方法2: module.replacements を使う

Hugoの設定ファイル（config.tomlまたはhugo.toml）で直接置き換えルールを設定する方法です。この方法は、go.modファイルを直接編集するよりも、Hugoの設定として管理したい場合に便利です。

[module]
  replacements = "github.com/yamadatt/hugo-theme-karuta -> ../my-hugo-theme"

  [[module.imports]]
    path = "github.com/yamadatt/hugo-theme-karuta"

replacements オプションで、github.com/yourname/my-hugo-theme というモジュールパスを ../my-hugo-theme というローカルパスに置き換えることを指定します。

ローカル開発の開始

以下のコマンドでサーバーを起動し、テーマの変更が即座にサイトに反映されることを確認しながら開発を進めます。

hugo server -D --disableFastRender --navigateToChanged

オプションの意味

  • -D 下書き（draft）記事も表示するオプションです。開発中に作成中の記事を確認する際に便利です。

  • --disableFastRender Hugo の高速レンダリング機能をオフにするオプションです。これにより、テーマやテンプレートの変更が確実に反映されます。高速レンダリングは一部の変更を見落とすことがあるため、テーマやテンプレートを開発中はオフにすることをおすすめします。

  • --navigateToChanged ファイル変更時に、ブラウザをその変更があったページに自動的に移動するオプションです。例えば、記事を保存すると、その記事ページに自動遷移するため、記事の確認がスムーズです。

デプロイ時はローカル接続の解除

ローカルでの開発が完了し、NetlifyやGitHub Actionsなどでサイトをデプロイする際には、ローカルテーマへの接続設定を解除する必要があります。

デプロイ環境ではローカルのフォルダ（例：../my-hugo-theme）にアクセスできないため、接続設定が残っているとビルドが失敗します。

解除方法

開発時に設定した方法に応じて、以下のいずれかの方法で接続を解除し、リモートリポジトリ（GitHubなど）を参照するように戻します。

方法1: go mod edit -replace を使った場合

以下のコマンドを実行して、go.modファイルに追加した置き換えルールを削除します。

go mod edit -dropreplace=github.com/yamadatt/hugo-theme-karuta

その後に、以下を忘れずに投入します。

hugo mod tidy

方法2: module.replacements を使った場合

config.toml（またはhugo.toml）に記述したreplacementsの行を削除またはコメントアウトします。

[module]
  # replacements = "github.com/yourname/my-hugo-theme -> ../my-hugo-theme" # この行を削除またはコメントアウト

  [[module.imports]]
    path = "github.com/yourname/my-hugo-theme"

この解除作業により、デプロイ時にはHugoがmodule.importsで指定されたリモートリポジトリからテーマを正しく取得するようになります。

テーマとサイトの関係図

graph TD
  A[my-hugo-theme<br>(テーマリポジトリ)]
  B[my-hugo-site<br>(サイトリポジトリ)]

  A -->|Hugo Modules経由| B
  subgraph Local Dev
    A -- "ローカル置換（replace/replacements）" --> B
  end

図の説明:

  • 通常、my-hugo-site は my-hugo-theme をGitHubなどのリモートリポジトリからHugo Modules経由で取得します。
  • しかし、開発時には「Local Dev」のサブグラフにあるように、go mod edit -replace コマンドや module.replacements 設定を使って、my-hugo-theme のローカルフォルダを直接参照するように置き換えます。
  • これにより、テーマの変更が即座にサイトに反映され、効率的な開発が可能になります。

まとめ

Hugo Modules を使うことで、テーマとサイトを独立して管理しつつ、開発時にはローカルでシームレスに連携できます。この方法は、テーマの再利用性や開発効率を大幅に向上させます。

  • テーマとサイトを別々にバージョン管理
  • 開発中の変更を即時プレビュー
  • 複数サイトでのテーマ共有
  • バージョン管理による安定運用

参考資料