https://ama-tech.hatenablog.com/hugo-github-pages

この記事ではHugoで作成したWebサイトをGitHub Pagesにデプロイする手順を紹介します。

1. 実行環境

Hugo：0.148.2
Git：2.43.0
MacBook Pro (13-inch, 2020)
macOS：Sequoia 15.6.1

2. 手順

2-1. Hugoサイトを作成

以下のコマンドを実行して、Hugoサイトを作成します。

$ hugo new site hugo_demo --format yaml
$ cd hugo_demo
$ git init

2-2. PaperModテーマをインストール

github.com

以下のコマンドを実行して、PaperModテーマをインストールします。

$ git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
$ echo "theme: ["PaperMod"]" >> hugo.yaml

2-3. テスト記事を作成

以下のコマンドを実行して、テスト記事を1件作成します。

$ hugo new content content/posts/my-first-post.md

作成されたcontent/posts/my-first-post.mdを以下のように修正します。

---
date: '2025-08-28T13:21:36+09:00'
- draft: true
+ draft: false
title: 'My First Post'
---
+ ## Introduction

+ This is **bold** text, and this is *emphasized* text.

+ Visit the [Hugo](https://gohugo.io) website!

以下のコマンドを実行して、public/配下をgitの管理対象から除外します。

$ echo "public/" > .gitignore

以下のコマンドを実行して、ローカルでHugoサーバーを起動します。

$ hugo server

ブラウザからhttp://localhost:1313/にアクセスしてサイトが正しく表示されることを確認します。

2-4. GitHub Pagesへデプロイ

gohugo.io

GitHubリポジトリを作成し、先ほど作成したHugoサイトをリポジトリにpushします。

GitHubリポジトリページのSettings > Pagesを選択して、Build and deploymentのSourceをDeploy from a branchからGitHub Actionsに変更します。(https://github.com/username/reponame/settings/pages)

hugo.yamlに以下を追記します。

baseURL: https://example.org/
languageCode: en-us
title: My New Hugo Site
theme: ["PaperMod"]
+ caches:
+   images:
+     dir: :cacheDir/images

以下のコマンドを実行して、デプロイ用のワークフローファイルを作成します。

$ mkdir -p .github/workflows
$ touch .github/workflows/hugo.yaml

.github/workflows/hugo.yamlに以下の内容を追記します。

name: Build and deploy
on:
  push:
    branches:
      - main
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
defaults:
  run:
    shell: bash
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DART_SASS_VERSION: 1.91.0
      GO_VERSION: 1.25.0
      HUGO_VERSION: 0.149.0
      NODE_VERSION: 22.18.0
      TZ: Europe/Oslo
    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: false
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Create directory for user-specific executable files
        run: |
          mkdir -p "${HOME}/.local"
      - name: Install Dart Sass
        run: |
          curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
          echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
      - name: Install Hugo
        run: |
          curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          mkdir "${HOME}/.local/hugo"
          tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
          echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
      - name: Verify installations
        run: |
          echo "Dart Sass: $(sass --version)"
          echo "Go: $(go version)"
          echo "Hugo: $(hugo version)"
          echo "Node.js: $(node --version)"
      - name: Install Node.js dependencies
        run: |
          [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
      - name: Configure Git
        run: |
          git config core.quotepath false
      - name: Cache restore
        id: cache-restore
        uses: actions/cache/restore@v4
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: hugo-${{ github.run_id }}
          restore-keys:
            hugo-
      - name: Build the site
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/" \
            --cacheDir "${{ runner.temp }}/hugo_cache"
      - name: Cache save
        id: cache-save
        uses: actions/cache/save@v4
        with:
          path: ${{ runner.temp }}/hugo_cache
          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

ここまでの変更をpushして、GitHub Pagesにデプロイします。

ブラウザからhttps://username.github.io/reponame/にアクセスしてサイトが正しく表示されることを確認します。