Hugoでこのブログを作成したので、その方法について書き残しておきます。

AWS に引っ越しました。 → ブログを AWS S3 + CloudFront に移転した (2021/04/27)

はじめに

静的サイト生成に Hugo を選択した理由

選択肢としては Hugo, Hexo, Jekyll などを検討し、 Markdown で記事を管理できれば良いと考えていました。

この中で

  • Jekyll はメジャーだがビルドが遅いらしい
  • Hexo はシンプルで使いやすそうだが情報が少ない
  • Hugo はある程度人気が高く、めちゃくちゃ速いらしい

との評判から Hugo を採用するに至りました。

実際、Markdown を書いて保存すると 数ms ~ 数十ms でホットリロードしてくれます。

また、簡単のためホスティングには GitHub Pages を使用しました。

インストール

環境

  • MacBook Pro (13-inch, M1, 2020)
  • macOS Big Sur Version 11.2.3

事前インストール

  • Homebrew (3.1.3)

Hugo をインストール

公式の Quick Start を参考にインストールしました。

以下コマンドで入ります。

brew install hugo

Hugo で Web サイトを作る

以下のコマンドを実行すると 初期設定された blog という名前のディレクトリが生成されます。

hugo new site blog

また、git で管理するために git init をしておきます。

cd blog
git init

適宜コミットしながら進めていきます。

テーマ（Theme）を追加する

Hugo では多くのテーマ(theme)が公開されており、簡単にいい感じの UI が手に入ります。

themes.gohugo.io にいろいろな theme があるのでダウンロードします。

今回はtranquilpeakを追加してみました。

git submodule として管理したいため、以下のようにします。

git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/tranquilpeak

追加した theme を使用するよう設定します。 エディタで直接変更してしまっても OK です。

echo theme = \"tranquilpeak\" >> config.toml

以上でダウンロードした theme が適用されるようになりました。

記事を追加する

記事を追加します。

hugo new post/new-post.md

実行すると content/post/new_post.md が作られ、このファイルの内容が記事になります。

ローカルサーバで確認

以下を実行するとローカルのサーバが立ち上がり、サイトの内容を確認することができます。

hugo server

また、下書き中の記事も表示させるには -D オプションを指定します。

hugo server -D

表示がうまく切り替わらない場合は --disableFastRender オプションを指定すると良いようです。

hugo server -D --disableFastRender

ローカルサーバが立ち上がったら、ブラウザからアクセスしてみます。

デフォルトの場合は http://localhost:1313 でアクセスできます。

この状態で Markdown や設定ファイルを編集・保存すると、リアルタイムで内容が反映されます。

設定ファイルをいじる

Hugo の設定ファイルは config.toml に記述します。（各 Markdown ファイル内のFront-matter で各記事ごとの設定ができます）

詳細は公式の Configure Hugo に載っています。

私が変更した主な箇所は以下です。

baseURL = "https://USERNAME.github.io/" # 自分のサイトのURL
googleAnalytics = "UA-xxxxxx" # Google Analytics を設定できる
theme = "tranquilpeak"

[author] # 以下適宜設定する
  name = ""
  bio = ""
  job = ""
  location = ""
[params]
  dateFormat = "2006/01/02"
  favicon = "" # 画像へのpath

  [[params.customCSS]] # 追加でCSSを設定する
    href = "css/optional.css" # static/css/optional.css が呼び出される

また、tranquilpeak では <!-- toc --> と記述すると目次を生成できる機能がありますが 生成されないバグがあるようで、issue #395 を参考に以下を追加しました。

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

ビルド・ホスティング

静的ファイルをビルドします。

hugo --minify コマンドを実行すると public ディレクトリ配下が Web サイト用コンテンツとして生成されます。

hogo のみでもビルドされますが、 --minify を指定すると圧縮されます。

ファイルサイズは小さい方が読み込みが高速になるため、こちらのオプションを使用することをお勧めします。

基本的には、これを何らかのホスティングサイトにアップロードするだけでデプロイ完了です。

当ブログでは GitHub Pages をホスティングに使用するため、次のような構成にしました。

  • ブログ用の記事を管理するためのリポジトリ（プライベート）を作成
  • GitHub Pages を使用するための [username].github.io リポジトリ（パブリック）を submodule として public ディレクトリに対応させる
  • 記事を書いて push すると github.io リポジトリを更新され、デプロイされるようにする

このようにすると公開用と編集用でリポジトリを分けることができ、編集中の記事や設定ファイルは非公開にすることができます。

実際に設定する

submodule の追加

username.github.io リポジトリを public ディレクトリに関連付けます。

git submodule add git@github.com:USERNAME/USERNAME.github.io public

このとき submodule が 2 つある状態となっており、 .gitmodules は以下のようになっています。

[submodule "themes/tranquilpeak"]
        path = themes/tranquilpeak
        url = https://github.com/kakawait/hugo-tranquilpeak-theme.git
[submodule "public"]
        path = public
        url = git@github.com:USERNAME/USERNAME.github.io

GitHub Actions の設定

親となっているリポジトリの .github/workflows 配下に publish.yml ファイルを追加し、以下のように設定しました。

今回は（私の癖で） submodule に SSH を使用しており、Deploy key と Secrets を設定しておく必要があります。

HTTPS の場合は PAT を使用し、よりシンプルに実現できると思います。

name: deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: Git checkout
        uses: actions/checkout@v2

      - name: Check out submodules
        env:
          SSH_KEY_FOR_SUBMODULE: ${{ secrets.SUBMOD_KEY }}
        run: |
          mkdir $HOME/.ssh && echo "$SSH_KEY_FOR_SUBMODULE" > $HOME/.ssh/id_rsa && chmod 600 $HOME/.ssh/id_rsa && 
          git submodule update --init --recursive

      - name: Switch github.io branch
        run: |
          cd public && git switch main && git pull origin main --ff-only

      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.82.1"

      - name: Build
        run: hugo --minify

      - name: Commit & Push changes
        run: |
          git config --global user.name github-actions && 
          git config --global user.email noreply@github.com && 
          cd public && git add . && git commit -m "generate" --allow-empty && git push origin main

結構長くなってしまいました。 今のところは変更していませんが、デプロイ用のシェルスクリプトを用意すると良さそうです。

以上を設定し commit, push すると GitHub Actions でビルドされ、GitHub Pages 上にサイトが公開されました。

おわりに

今回は Hugo + GitHub Actions でのブログ構築作業についてまとめてみました。

今後設定を変更したりするかと思いますが、順次更新していきたいと思います。