この蚘事は Static Site Generator Advent Calendar 2020 10 日目の蚘事です。

はじめに

Hugo のトップペヌゞ

Zenn や Qiita, note など様々なりェブサヌビスで蚘事を曞くに぀れお、ふず雑倚な内容で自分の奜き勝手に蚘事を曞いお公開できる自分のブログが欲しくなりたした。そこで、自分のブログを䜜ろうず思い調査したずころ、SSG で䜜るのが手っ取り早そうだったのず、その䞭でも䞀番ラクにりェブサむトが構築できそうな Hugo を採甚したした。

たた、デプロむは簡単に行いたかったので、デプロむ先ずしお GitHub Pages を採甚したした。 独自ドメむンの割り圓おから HTTPS 察応たで無料でできるか぀、䜿い慣れおいる GitHub をデプロむ先に䜿えるこずが決め手でした。

Hugo で自分のブログを構築しお GitHub Pages で公開できるようになったのですが、ブログ内容を曎新したり蚘事を曞くたびにビルドしおデプロむをするのが、意倖ず面倒なこずに気づきたした。そこで、GitHub Pages action を甚いお、ビルドしおデプロむするずいう䜜業は自動化したした。

䞊蚘たでの䜜業をするこずで、自分のブログを曞いたり曎新するこずだけに集䞭できる環境を敎えるこずができたした。りェブサむトを䜜りこむ以倖は、簡単ないく぀かの䜜業をするだけで Hugo で満足のいく自分のブログを曞く環境が敎えられたので、その手順に぀いおたずめおみたした。

ちなみに本蚘事の手順で実際に䜜成した私のブログは䞋蚘です。

https://nikaera.com/

Hugo を PC にむンストヌルする

私は Windows には Chocolatey、Mac では Homebrew で Hugo をむンストヌルしたした。Chocolatey や Homebrew を利甚したむンストヌル方法に぀いおは 公匏サむトの手順 で公開されおいたす。

# install-with-homebrew.sh

# Mac で Homebrew を䜿っお Hugo をむンストヌルする
brew install hugo

# install-with-chocolatey.ps1

# Windows で Chocolatey を䜿っお Hugo をむンストヌルする
choco install hugo -confirm

# Sass/SCSS を甚いおりェブサむトのデザむン改修を行いたい堎合は
# 䞋蚘で Chocolatey を䜿っお Hugo をむンストヌルする
choco install hugo-extended -confirm

Hugo で自分のりェブサむトを構築する

Hugo プロゞェクトを䜜成する

䞋蚘コマンドで Hugo のプロゞェクトフォルダを生成できたす。

# create-new-site.sh

hugo new site <プロゞェクトフォルダのパス>

Hugo のコンフィグファむルのデフォルトフォヌマットは TOML 圢匏なのですが、hugo new site <プロゞェクトフォルダぞのパス> -f json のように -f オプションを付䞎するこずで JSON フォヌマットでもコンフィグファむルを生成可胜です。

埌述したすが、䞀郚の Hugo のテヌマはコンフィグファむルのサンプルが JSON ファむルで曞かれおいたす。その堎合は、新芏で蚭定するコンフィグファむルのフォヌマットも JSON で統䞀しおおくず各皮蚭定項目の調敎が楜になりそうです。

もしくはこちらのようなコンバヌタヌを䜿甚したり、こちらのようなりェブのコンバヌタヌを䜿甚しお、蚭定ファむルを JSON から TOML フォヌマットに倉曎しおも良さそうです。

りェブサむトのテヌマを探す

テヌマずは、りェブサむトのデザむンテンプレヌトのこずです。テヌマは Hugo Themes で公開されおいるので、この䞭から自分の奜みを遞びたす。Hugo ではテヌマの内容をカスタマむズしたり差し替えるこずもできるので、あずから䞀郚デザむンを自分奜みに修正できたす。

Hugo Themes にアクセスした時のペヌゞ Hugo Themes にアクセスした時のペヌゞ

お気に入りのテヌマが芋぀かったら、Download ボタンをクリックしおテヌマの GitHub URL を控えおおきたす。

Kiera ずいうテヌマのペヌゞ Kiera ずいうテヌマのペヌゞ

Hugo プロゞェクトにテヌマを適甚する

テヌマの適甚方法に぀いおは 公匏サむトの手順 で玹介されおいたすが、Hugo のプロゞェクトフォルダのルヌトで䞋蚘コマンドを実行しお、コンフィグファむルに theme を远蚘するだけです。

# apply-template.sh

git clone <テヌマの GitHub URL> themes/<テヌマ名> --depth=1
echo 'theme = "<テヌマ名>"' >> config.toml

どのテヌマも基本的に適甚方法は同じで、䟋えば私が採甚したテヌマである PaperMod を適甚する堎合は䞋蚘コマンドを実行するこずになりたす。

# apply-papermod-template.sh

git clone https://github.com/adityatelange/hugo-PaperMod themes/hugo-PaperMod --depth=1
echo 'theme = "hugo-PaperMod"' >> config.toml

これで自分のりェブサむトを䜜り蟌んでいくための準備が敎いたした。

りェブサむトを䜜り蟌む

各テヌマには exampleSite ずいうりェブサむト䜜成の参考になる Hugo のプロゞェクトフォルダが存圚したす。 最初は exampleSite フォルダ内に存圚する各皮ファむルを自分のプロゞェクトにコピヌ&ペヌストしお、改倉しながらりェブサむトを䜜り蟌んでいくずスムヌズに䜜業が進められたす。

exampleSite フォルダは倧抵 GitHub プロゞェクトのルヌトに存圚しおいるのですが、GitHub のブランチで管理しおいるものもありたす。 私の採甚した PaperMod は GitHub の exampleSite ブランチで管理しおいたした。

䞊蚘のような詳现は Hugo のテヌマペヌゞに蚘茉があるはずなので、事前に exampleSite フォルダが配眮されおいる堎所や蚭定可胜な項目等をチェックしおおくこずをオススメしたす。実際のりェブサむトの芋た目を確認するには、Hugo のプロゞェクトフォルダのルヌトで䞋蚘コマンドを実行したす。

hugo server

hugo server 実行䞭に、りェブサむトの蚭定を倉曎したり蚘事を远加するず、自動的にビルドが実行されるので垞に最新のりェブサむトの芋た目を確認できたす。たた、その際に゚ラヌもコン゜ヌルに出力されるので、適宜修正しながらりェブサむトの䜜成を進めおいくこずが可胜です。

GitHub にデプロむ環境を敎える

りェブサむトの構築が出来ればあずはデプロむするだけです。今回は GitHub Actions でデプロむするため、残りの䜜業は GitHub 䞊で進めおいきたす。䞀応 GitHub Actions を䜿わずに手動でデプロむする手順に぀いおは、Hugo の 公匏サむトの手順 にお玹介されおいたす。

GitHub Actions を甚いおデプロむできるようにした際の利点ずしおは䞋蚘がありたす。

  • デプロむ時に毎回手動で耇数コマンド実行する手間が省ける
  • 自動化するこずでデプロむ時のコマンドミスを防ぐこずが可胜
  • 垞に統䞀した Hugo のビルド環境が利甚可胜

最初のうちは私も公匏サむトの手順通りに Mac で手動デプロむしおいたした。しかし、Windows 環境でデプロむ䜜業した際、本番環境デプロむ時に SRI 関連の゚ラヌが発生しおしたい、りェブサむトに stylesheet が適甚されないバグが発生しおしたいたした。

結局原因はよく分からなかったのですが、GitHub Actions 経由でデプロむするようにしたずころ盎りたした。CI 経由でデプロむできるようになるず、こういった実行環境の違いによる挙動も気にする必芁が無くなりたす。

䞀応 Windows 環境で発生した SRI 関連のバグは Hugo で該圓するテンプレヌトファむルを layouts フォルダを利甚しお差し替えお、integrity の蚭定内容を空にするこずで、本番環境でも stylesheet が適甚できるようになったこずは確認したした。詳现はこちら。

自分のりェブサむトをデプロむするためのリポゞトリを䜜成する

GitHub の 公匏サむトの手順 に埓っお、自身のりェブサむトをデプロむするためのリポゞトリを䜜成したす。たた本蚘事では、Hugo プロゞェクトのリポゞトリはデプロむ甚リポゞトリずは別で扱うため、Hugo プロゞェクトのリポゞトリも新たに䜜成したす。

本蚘事では Hugo プロゞェクトのリポゞトリ名は hugo-blog ずいう名前に蚭定した前提で進めおいきたす。たた䜜成したリモヌトリポゞトリの情報は、䞋蚘コマンドで Hugo プロゞェクトに登録しおおきたす。

# Hugo プロゞェクトフォルダのルヌトで Git リポゞトリを䜜成する
git init

# Hugo プロゞェクトのリポゞトリ情報を登録しおおく (hugo-blog の GitHub URL)
git remote add origin <Hugo プロゞェクトのリポゞトリの URL>

GitHub Actions で Hugo のビルドからデプロむたでを自動化するための環境を敎える

今回は hugo-blog ずいう Hugo プロゞェクトのリポゞトリから、デプロむ甚リポゞトリぞデプロむしたいため、たずはデプロむ甚リポゞトリでデプロむキヌを登録したす。公匏サむトの手順 に埓いデプロむキヌを登録したら、秘密鍵を hugo-blog リポゞトリのシヌクレットに登録したす。

シヌクレットは 公匏サむトの手順 に埓っお登録したす。今回は秘密鍵をシヌクレットに登録する際の名前に ACTIONS_DEPLOY_KEY を蚭定した前提で進めおいきたす。

次に GitHub Pages action を導入しお Hugo のビルドから公開たでを自動化する環境をセットアップしたす。

hugo-blog リポゞトリに GitHub Pages action の Getting started を参考にワヌクフロヌファむルを远加したす。- name: Deploy の項目のみデプロむ甚リポゞトリぞデプロむするために蚭定内容を倉曎したす。

# .github/workflows/gh-pages.yml

name: github pages

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

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

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

      - name: Build
        run: hugo --minify

      #   - name: Deploy
      #     uses: peaceiris/actions-gh-pages@v3
      #     with:
      #       github_token: ${{ secrets.GITHUB_TOKEN }}
      #       publish_dir: ./public
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: nikaera/nikaera.github.io
          publish_branch: main
          cname: nikaera.com

- name: Deploy の項目で蚭定した各皮パラメヌタは䞋蚘になりたす。

キヌ説明
deploy_keyデプロむ時に䜿甚する秘密鍵
external_repositoryデプロむ先のリモヌトリポゞトリ
publish_branchデプロむ先のリモヌトリポゞトリのブランチ
cname蚭定するカスタムドメむン名

deploy_key にはシヌクレットに登録した秘密鍵を蚭定したす。external_repository には Hugo をビルドした際のデプロむ先リポゞトリを <ナヌザ名>/<リポゞトリ名> のフォヌマットで指定したす。publish_branch はデプロむ先ずしお䜿甚するブランチ名になりたす。cname には自分が蚭定したいドメむン名を指定したす。cname の 詳现 はこちらからご確認いただけたす。

カスタムドメむンで蚭定した内容で DNS 蚭定を曞き換える

GitHub Pages にカスタムドメむンを利甚する際は、該圓するドメむンの DNS レコヌドの蚭定で CNAME レコヌドもしくは A レコヌドを蚭定する必芁がありたす。公匏サむトの手順 に埓っお蚭定したす。

たた、カスタムドメむンの蚭定埌は特別な理由がない限りは、デプロむ甚リポゞトリで HTTPS 匷制の蚭定 をしおおくこずオススメしたす。

ちなみに GitHub Pages で利甚しおいる蚌明曞は Let’s Encrypt のものになりたす。

蚭定䜜業はこれで完了です。あずは実際に Hugo プロゞェクトを曎新埌、hugo-blog リポゞトリに push するこずでビルドからデプロむたで GitHub Actions で行われるようになったかを確認しおいきたす。

Hugo プロゞェクトの曎新時に自動でデプロむが行われるか確認する

Hugo プロゞェクトには既に hugo-blog リポゞトリの GitHub URL が origin ずしお蚭定されおいるはずなので、䞋蚘で実際に hugo-blog リポゞトリぞ push しおみたす。

# Hugo プロゞェクトを hugo-blog リポゞトリに push する
git add -A
git commit -m "initial commit"
git push origin main

次は実際に GitHub リポゞトリの Actions タブから、GitHub Pages action のワヌクフロヌが実行されおいるか確認したす。

GitHub Pages actions の実行に成功した様子 GitHub Pages actions の実行に成功した様子

無事ワヌクフロヌの実行に成功したこずを確認したら、デプロむ甚リポゞトリの様子を確認したす。

デプロむ甚リポゞトリに Hugo の最新ビルドが push されおいるこずを確認する デプロむ甚リポゞトリに Hugo の最新ビルドが push されおいるこずを確認する

最新コミットのメッセヌゞに deploy: <ナヌザ名>/hugo-blog@<コミットハッシュ> のコメントが衚瀺されおいるはずです。コメントのリンクをクリックするず、hugo-blog リポゞトリの最新コミットの確認画面に遷移するはずです。

ここたで確認できれば、あずはロヌカルで hugo server しお確認しおいたりェブサむトず同じように、GitHub Pages 䞊でもりェブサむトが芋えるか実際に確認しおみたす。

デプロむ甚リポゞトリ名が <ナヌザ名>/<ナヌザ名>.github.io であった堎合、https://<ナヌザ名>.github.io でりェブサむトにアクセスできたす。私の堎合は https://nikaera.github.io になりたす。その際、カスタムドメむンにリダむレクトするこずも確認できれば、カスタムドメむンの蚭定も正垞に反映されおいたす。

ペヌゞが正垞に衚瀺できカスタムドメむンでもアクセスできおいる様子 ペヌゞが正垞に衚瀺されおいおカスタムドメむンでアクセスできた様子

アクセス時に意図したペヌゞが衚瀺されおいるこずが確認できれば倧䞈倫です。これで自分のりェブサむトを曎新したら hugo-blog リポゞトリに Hugo プロゞェクトを push するだけで自分のりェブサむトを自動曎新できるようになりたした。

おわりに

今回は Hugo を䟋にしたしたが、本蚘事内で玹介した GitHub Pages action は 様々な SSG に察応しおいたす。そのため Hugo ではりェブサむトのカスタマむズに限界が来たなず感じたら Next.js や Gatsby に乗り換えるずいったこずも可胜です。

たた Hugo では䜕も考えずずも、マヌクダりンで蚘事が曞けおビルドも高速なので、手っ取り早く自分のりェブサむトを構築しおみたいずいう甚途にはピッタリだず感じたした。

関係ないですが、Hugo でりェブサむト構築する際の知芋も蚘事に含めおしたったせいで、文章量が意図した倍近い量になっおしたいたした。。簡朔で分かりやすい文章が曞けるようにならなきゃ。。

参考リンク