Hugo + GitHub Action + Github Pages、ブログの自動公開を構築

私の提案は以下の 2 つのコア部分から成り立っています：

ブログソースリポジトリは、ブログの設定およびすべての文章 .md ソースファイルのバージョン管理を行い、GitHub Action と連携して自動デプロイを行い、静的サイトを自動生成して GitHub Pages ブログ公開リポジトリにプッシュします。
GitHub Pages ブログ公開リポジトリは、GitHub Pages を使用してウェブサイトをデプロイし、CNAME でドメイン名を解決してカスタムドメインを使用できます。

Hugo を使用してブログを構築する#

Hugo は Go で実装されたブログツールで、Markdown を使用して記事を編集し、静的サイトファイルを生成します。豊富なテーマ設定をサポートし、js を通じてコメントシステムなどのプラグインを埋め込むこともでき、高度にカスタマイズ可能です。Hugo の他にも、Gatsby、Jekyll、Hexo、Ghost などの選択肢がありますが、実現と使用はほぼ同じで、自分の好みに応じて選択できます。

Hugo のインストール#

私は macOS を使用しているため、公式に推奨されている homebrew 方式で hugo プログラムをインストールします。他のシステムについては公式ドキュメントを参照してください。

brew install hugo

完了後、以下のコマンドで確認します（バージョン番号を確認）：

hugo version

Hugo サイトの作成#

hugo new site blog-demo

テーマの設定#

サイトを作成した後、テーマの設定を行う必要があります。Hugo コミュニティには非常に豊富なテーマがあり、公式サイトの Themes メニューから好みのスタイルを選択し、プレビュー効果を確認できます。選択後、テーマプロジェクトリポジトリに入ることができ、一般的に詳細なインストールおよび設定説明があります。以下では、私が現在使用している smol というテーマを例に、設定プロセスを示します。

cd blog-demo
git clone [email protected]:colorchestra/smol.git themes/smol
cd themes/smol
rm -rf .git

テーマの基本設定を初期化した後、config.toml ファイルでサイトの詳細設定を行います。具体的な設定項目はテーマの説明文書を参照してください。

config.toml の内容を参考にしてください

theme = "smol"

新しい記事の公開#

hugo new posts/blog-test.md

ローカルでのサイトデバッグ#

ローカルでリアルタイムデバッグプレビューを行います。

hugo server

サービスを実行した後、ブラウザで http://localhost:1313 アドレスにアクセスしてローカルプレビューウェブページを表示できます。

GITHUB PAGES リポジトリ#

GitHub Pages リポジトリの設定が完了した後、設定で自分が登録したカスタムドメインを GitHub Pages が生成した URL に指向させることができます。さらに、ブログサイトの設定ファイル config.toml 内の baseURL を自分のカスタムドメインに変更する必要があります。

GitHub Pages でブログを公開#

現在、カスタムドメインを使用して GitHub Pages ページにアクセスできるようになりましたが、プロジェクトリポジトリが空のため、アクセスすると 404 ページが表示されます。

Hugo が生成した静的ウェブサイトは GitHub Pages サービスでホスティングされるため、Hugo が生成した静的ウェブページファイルを GitHub Page プロジェクトリポジトリにアップロードする必要があります。

手動公開#

hugo
cd public

Hugo はデフォルトで生成された静的ウェブページファイルを public / ディレクトリに保存します。public / ディレクトリを git リポジトリとして初期化し、私たちの clin003/blog_html リモートリポジトリに関連付けることで、ウェブページの静的ファイルをプッシュできます。

git init
git remote add origin [email protected]:baicaime/meBlog
git add .
git commit -m "debug"
git push origin main

GitHub Pages リポジトリにプッシュした後、数分待つとカスタムドメインを通じてブログサイトにアクセスできるようになります。これは

hugo server

ローカルデバッグと完全に一致します。

自動公開#

私たちのブログは GitHub と GitHub Pages に基づいているため、公式が提供する GitHub Action を使用して CI 自動公開を行うことができます。
GitHub Action は継続的インテグレーションおよび継続的デリバリー（CI/CD）プラットフォームで、ビルド、テスト、デプロイパイプラインを自動的に実行するために使用でき、簡単な設定で直接使用できます。

リポジトリディレクトリ
.github/workflows
に設定し、.yml を拡張子とします。私の GitHub Action 設定は
deploy.yml
自動公開のサンプル設定は以下の通りです：

name: Deploy Hugo site to Pages
on:
  push:
    branches: [ "main" ]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
defaults:
  run:
    shell: bash
env:
  NAME: BLOG_push
  # プッシュ先リポジトリのフォーマット ユーザー名/リポジトリ名
  TARGET_REPOSITORY_NAME: baicaime/meBlog
  # 同期用一時ディレクトリ（オプション）
  CLONE_DIR: tmp_public
  # ビルド用一時ディレクトリ（オプション）
  BUILD_DIR: tmp_build
  # gitユーザー名の設定
  GIT_USERNAME: baicaime


jobs:
  # このワークフローには「build」と呼ばれる単一のジョブがあります
  build:    
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.117.0    
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - uses: actions/checkout@v3
      - name: Build with Hugo
        env:
          # Hugoモジュールとの最大の後方互換性のため
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            -d ${{ env.BUILD_DIR }}
      
      - name: Git Config
        run: |
          git config --global user.email "[email protected]"
          git config --global user.name "${{ env.GIT_USERNAME }}"
          echo "gitの設定が完了しました"

      - name: Git clone
        run: |
          echo "ターゲットリポジトリの同期（開始）"
          git clone --depth 1 https://github.com/${{ env.TARGET_REPOSITORY_NAME }}.git ${{ env.CLONE_DIR }} &> /dev/null
          echo "ターゲットリポジトリの同期（完了）"

      - name: Git push
        run: |
          cp -rf ${{ env.BUILD_DIR }}/*  ${{ env.CLONE_DIR }}/
          cd ${{ env.CLONE_DIR }}
          echo "${{ github.event.head_commit.message }} `date +%FT%T%z`" > _pub_time.html         
          git add .
          git commit --message "Update ${{ env.NAME }} from ${{ env.TARGET_REPOSITORY_NAME }} ${{ github.event.head_commit.message }}"
          git push -f -q https://oauth2:${{ secrets.GIT_TOKEN }}@github.com/${{ env.TARGET_REPOSITORY_NAME }}.git main
          echo  "git push  ${{ env.TARGET_REPOSITORY_NAME }}（完了）"

on は GitHub Action のトリガー条件を示し、私は push と workflow_dispatch の 2 つの条件を設定しました：

push：このプロジェクトリポジトリにプッシュアクションが発生したとき、GitHub Action を実行します。
workflow_dispatch：GitHub プロジェクトリポジトリの Action ツールバーで手動で呼び出すことができます。

jobs は GitHub Action 内のタスクを示し、私たちは build タスクを設定しました。
runs-on は GitHub Action の実行環境を示し、私たちは ubuntu-latest を選択しました。
build タスクには、Install Hugo CLI、Checkout、Build with Hugo、Git Config、Git clone、Git push の 6 つの主要なステップが含まれています。
その中で run は実行するコマンドで、uses は GitHub Action 内のプラグインで、私たちは actions/checkout というプラグインを使用しています。
Checkout ステップでは、with 内で submodules の値を true に設定することで、ブログソースリポジトリのサブモジュール（テーマモジュールなど）を同期できます（私たちはサブモジュール方式で hugo テーマをインストールしていないため、このパラメータは必要ありません）。

上記の deploy.yml 内の設定を変更する必要があります：#

TARGET_REPOSITORY_NAMEを自分のGitHub Pagesリポジトリに変更します。私の設定はbaicaime/meBlogです。
GIT_USERNAMEを自分のGitHub Pagesリポジトリのユーザー名に変更します。

ブログリポジトリから外部 GitHub Pages リポジトリにプッシュする必要があるため、特定の権限が必要です。GitHub アカウントの設定 - 開発者設定 - パーソナルアクセストークンでトークンを作成する必要があります。

必要な権限：

Contents 	read/write

設定後、生成されたトークンをコピーします（注：一度だけ表示されます）。その後、ブログソースリポジトリの

Settings - secrets and variables - Actions

に追加します。

GIT_TOKEN

環境変数は先ほどのトークンで、これにより GitHub Action はトークンを取得できるようになります。

プッシュテスト#

上記の設定が完了したら、リポジトリにコードをプッシュすることで GitHub Action がトリガーされ、自動的にブログページが生成され、GitHub Pages リポジトリにプッシュされます。

GitHub Pages リポジトリが更新されると、公式のページデプロイ CI が自動的にトリガーされ、ウェブサイトが公開されます。

今では、私たちがローカルで慣れ親しんだ Markdown 構文を使用してブログコンテンツの編集を完了した後、コードをプッシュし、数分待つだけで、カスタムドメインを通じて更新されたウェブサイトにアクセスできるようになります。

以上が、私が Hugo と GitHub Action を使用して実現したブログ自動デプロイシステムです。私自身の実装リポジトリはbaicaime/meBlogにあります。