テーマをHugo Modulesベースで扱うHugoプロジェクトの作り方

Hugo テーマを取り飲むのに以前からのthemes/に配置する方法ではなく、Hugo Modulesを用いて外部参照して使用する方法。

0. 事前準備

Hugo Modulesを使うには、hugoコマンドの他に、

• gitコマンド
• goコマンド(golangパッケージ内)

が必須になるので、プラットフォームごとの手段でインストールしておくこと。

1. 空プロジェクトから作る方法

作る前に、Hugoプロジェクト自体のMod IDを決めておく必要がある。

ふつうは、(実際にpushする必要はなくても、)ソースであるHugoプロジェクトをgithubに置く前提で命名する。

• organization/repositoryが、それぞれexample-org/example-org.github.ioという名前である場合、Mod IDはgithub.com/example-org/example-org.github.ioとなる。

Hugoプロジェクト自体のディレクトリ名は適当な名前もよい。

$ mkdir example-org-site/
$ cd example-org-site/
$ hugo mod init github.com/example-org/example-org.github.io
$ mkdir content/
$ emacs hugo.toml

たとえば、Hugo Bear Blogテーマを使用するものとする場合を扱う。

• https://themes.gohugo.io/themes/hugo-bearblog/

テーマの説明の中に、git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblogという記述がある。

この中のgitリポジトリのURL https://github.com/janraasch/hugo-bearblog.gitから、 テーマのMod IDはgithub.com/janraasch/hugo-bearblogと決まる(必ずhttps://と.gitは外す)。

最初のhugo.tomlの内容は、テーマをインポートする記述だけをする:

[module]
  [[module.imports]]
    path = "github.com/janraasch/hugo-bearblog"

(注: hugo-bearblogは違うが、テーマによってはSCSSなどのビルドのための環境の用意(sassc等)が必要になる場合がある)

この時点で、ディレクトリの下には、以下のファイルができている:

• hugo.toml
• go.mod
• content/
• resources/_gen/

(go.modとresources/_gen/以下は、hugo mod initで作られる)

ここで、サーバを立ち上げれば、テーマがダウンロードされ、http://localhost:1313/のWebページに適用されることをブラウザで確認する。

$ hugo server

つぎに記事を追加できることを確認する。

$ hugo new blog/first-post.md
$ emacs content/blog/first-post.md

その後は、これまでと同様に、hugo.tomlでテーマの設定を変更などを行っていくことになるだろう。

2. Github ActionsでビルドしてGithub Pagesで公開する方法

続いて、hugo modベースのHugoプロジェクトを、gitリポジトリ化し、github上にpushし、Github ActionsでHTMLサイトをビルドさせてGithub Pagesで公開するまで行う。

gitリポジトリ化

$ cd example-org-site/
$ git init
$ emacs .gitignore
$ git add .gitignore hugo.toml go.mod go.sum content/
$ git commit -m "[init]"

Hugoプロジェクトのための.gitignoreファイルのの内容は、以下のとおり:

/public/
/resources/_gen/
/assets/jsconfig.json
/.hugo_build.lock
hugo_stats.json

Github Actionsの設定

以下の内容の.github/workflows/gh-pages.ymlを追加する:

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Go
        uses: actions/setup-go@v4.0.0
        with:
          go-version: '^1.20'

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.113.0'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        # If you're changing the branch from main,
        # also change the `main` in `refs/heads/main`
        # below accordingly.
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Hugo Modulesを使う場合はgoコマンドも必要なため、actions-hugoのREADMEにあるymlの内容のBuildステップの前に、setup-goを加えたものになる。

• https://github.com/peaceiris/actions-hugo
• https://github.com/actions/setup-go

$ mkdir .github/workflows/
$ emacs .github/workflows/gh-pages.yml
$ git add .github/
$ git commit -m "[add] .github/workflows/gh-pages.yml"
$ git push origin HEAD

Actionsで、pages build and deploymentが終了したあと、 Github Pagesを有効化するために、github.com上のリポジトリページで、Settings - PagesのBranchをgh-pagesに変えれば、Webページが表示できるようになる。

A. 既存のHugoサイトをHugo ModulesベースのHugoプロジェクトに変更する方法

失敗しやすいので、作業をする前に Hugoサイトをまずバックアップしておく べきである。 Githubにおいてあるなら、別途git cloneしたもの(--recursiveなし)で作業すべきである。

A.1. テーマを消す

hugo mod initでもhugo.tomlを解釈するので、後に不要になるものを先に外しておく。

テーマはbinarioを使っているとする。

• https://themes.gohugo.io/themes/binario/

A.1,1. hugo.tomlからthemeを消す

hugo.toml内から、

theme = "binario"

を削除する。

A.1.2. themes/ディレクトリのクリーンアップ

themes/binarioを消す。

• zip展開やgit cloneでの展開であれば、themes/ディレクトリごと削除するだけ

ただし、git submoduleでテーマを導入している場合は、以下の手順で行う:

$ git submodule deinit -f themes/binario
$ git rm -rf themes/
$ git rm .gitmodules
$ rm -rf .git/modules/

A.2. hugo mod init

Github上のorganization/repositoryがbellbind-trial/bellbind-trial.github.ioなので、

$ hugo mod init github.com/bellbind-trial/bellbind-trial.github.io

を実行する。

A.3. テーマの追加

hugo.tomlに以下のエントリーを加える(一番下でよい):

テーマのgitリポジトリのURLがhttps://github.com/vimux/binarioであるため、Mod IDはgithub.com/vimux/binarioになる。

[module]
  [[module.imports]]
    path = "github.com/vimux/binario"

A.4. .github/workflows/gh-pages.ymlの編集

Buildステップの前に、setup-goのエントリーを加える:

    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
# ここから
      - name: Setup Go
        uses: actions/setup-go@v4.0.0
        with:
          go-version: '^1.20'
# ここまで
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.113.0'

      - name: Build
        run: hugo --minify

A.5. hugo serverで確認

gitリポジトリへ反映する前に、hugo serverで以前と同じように表示されることを確認する。

うまく表示されていない場合、git cloneから、途中で失敗しないようにしてやり直したらうまくいくかもしれない。

A.6. git commitし、githubへpush

$ git add hugo.toml .github/
$ git commit -m "[switch] to hugo mod"
$ git push origin HEAD

Github Actionsが成功することを確認し、Webページが表示されることを確認する。

B. 共有キャッシュを消すコマンド: hugo mod clean

現状、テーマのような外部のHugo Modulesは、Hugoプロジェクトごとに保持するのではなく、ローカルマシン上で別途、共有してキャッシュされている。

全キャッシュを消すコマンド:

$ hugo mod clean --all

たとえばhugo serverを立ち上げて、テーマモジュールのセットアップ中などに強制終了させた場合、その後のhugo serverのHTML生成がおかしくなる場合がある。 そういう場合には、一度キャッシュを全部消して、やり直すとなおるかもしれない。

C. 依存モジュールを最新版にアップデートするコマンド: hugo mod get -u

すべての依存モジュールを最新バージョンに更新するコマンド:

$ hugo mod get -u ./...

• 注: hugo mod get -uの引数の./...は例示ではない。そのまま打ち込むこと

この操作によって、go.modとgo.sumファイルの内容が更新されるので、gitリポジトリにも反映させる。

$ git add go.mod go.sum
$ git commit