😎

HugoのGettingStartedやってみた。Github Pagesで静的サイトを公開する

2025/08/07に公開

GitHub

Hugo

tech

はじめに

ZENNを愛用しているのですが、投稿数制限に引っかかり、サポートの返答もいまいちなので乗り換え先を探していました。Qiitaにしようかと思ったのですが、Qiitaも投稿数制限があるとのこと。あと、技術関係ではないポエムを書けないのでどこに書けばよいのか悩んでいました。

HUGOというフレームワークを使うと簡単にGithubと連携してサイトを作れるようなので、調べてみます。

Hugoとは

Hugoはオープンソースの最も人気の静的サイトジェネーレータのうちの１つだそうです。マスコットがGopherににていますね。Goで実装されているのでしょうか。

高速性と拡張性が強みだそうです。
2025年8月5日現在で82674のスターを得ているそうです。
スタートボタン押せよって言われたので押しときました。

月に２回くらいはリリースされていてアクティブに開発が進められているようです。
ということで触ってみます。

Getting Started

まずは Quick startしてみます

クイックスタート

サイトを作って
コンテンツを追加して
サイトの設定をして
公開します

事前準備は

Hugoのインストール
Gitのインストール

Hugoのインストール

macにインストールする

Hugoには３つの異なる版があるそうです。

standard
extended：Webpを使う。SassをCssにする。
extended/deploy：上記に加え、Google Cloud Storage、AWS S3、Azure Storageにデプロイできる

上記要件がなければstandardがオススメとのこと。

Homebrewでインストールします。

brew install hugo

サイトを作成する

Gitはインストール済みなのでサイト作成に進みます。

クイックスタートのディレクトリ構造を作ります。

hugo new site quickstart

作成したディレクトリに入ります。

cd quickstart

Gitレポジトリを初期化します。

git init

AnankeテーマをthemesにクローンしてGit submoduleとして追加します。

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

サイトの設定にテーマ設定を追加します。

echo "theme = 'ananke'" >> hugo.toml

Hugoの開発サーバを起動してサイトを見ます

hugo server

起動しました！

次にコンテンツを追加してみます。

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

以下の内容で my-first-post.md が作成されます。

+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++

フロントマッターのdraftがtrueの場合は公開されません。

コンテンツを追加してみます。

+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++
## Introduction

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

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

ファイルを保存したら開発サーバを開始します。draftコンテンツを含めるには以下のいずれかのコマンドを実行します。

hugo server --buildDrafts
hugo server -D

更新された！

コンテンツの出来に満足したらdraftをfalseにしましょう。

サイトの設定をする

ルートにある hugo.toml ファイルを開きます。

以下を設定するようです

baseURL
languageCode
title

baesURLは何を設定すればよいかわからないので、とりあえず languageCode title のみを入れました。
baseURLはgithub pagesを設定する想定です。

baseURL = 'https://example.org/'
languageCode = 'ja-JP'
title = "Kiitosu's Site"
theme = 'ananke'

サイトを公開できるように成果物を生成する

ここで公開の準備はしますが、デプロイはまだ行いません。

public ディレクトリに静的サイトを生成します。

つまり、HTMLファイル、画像などのアセット、CSSファイル、JavaScriptファイルなどです。

公開するときは、draft、未来の日付、期限切れ、などは含めません。
以下コマンドで公開ファイルを作成できます。

hugo

サイトをホスト、デプロイする

Github Pagesを使います。

事前準備

Githubアカウントを作成する
GItをインストールする
Hugoのサイトを作る

Github Pagesには3つのタイプが有ります。 project user organization です。それぞれGithubの プロジェクト ユーザ 組織 に紐づいています。

手順

Github レポジトリを作成する
レポジトリをGithubにpushする
Settings -> Pagesを選択します
SourceとしてGithub Actions を選択する
画像のキャッシュを配置する場所を変更するため以下の設定を追記します

[caches]
  [caches.images]
    dir = ':cacheDir/images'

.github/workflows に hugo.yaml を作成します

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

内容は以下

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    # GitHub-hosted runners automatically enable `set -eo pipefail` for Bash shells.
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      DART_SASS_VERSION: 1.89.2
      HUGO_VERSION: 0.148.0
      HUGO_ENVIRONMENT: production
      TZ: America/Los_Angeles
    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
      - name: Install Dart Sass
        run: |
          wget -O ${{ runner.temp }}/dart-sass.tar.gz https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
          tar -xf ${{ runner.temp }}/dart-sass.tar.gz --directory ${{ runner.temp }}
          mv ${{ runner.temp }}/dart-sass/ /usr/local/bin
          echo "/usr/local/bin/dart-sass" >> $GITHUB_PATH
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - 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: Configure Git
        run: git config core.quotepath false
      - name: Build with Hugo
        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

  # Deployment job
  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

変更をコミットし、プッシュします

git add -A
git commit -m "Create hugo.yaml"
git push

あとはGithub Actionsが動けばOK

公開された！

追加したコンテンツが表示されていないですね。
これはdraftがtrueだからだと思われます。falseにして試してみます。
初回投稿が反映されました！

気になるところ

hugo.toml の baseURL は以下の設定のままなのですが、問題ないのでしょうか。

baseURL = 'https://example.org/'

chatGPTにきいてみたところ以下の理由のようです。

baseURL を省略すると、Hugo は相対パスでリンクやアセットを生成
- 例: /css/style.css ではなく css/style.css のようなリンクになる
- GitHub Pages のデフォルト公開設定では、この相対パスがそのまま機能する

ということでこのままでも問題なさそうですが、以前baseURLが原因でインシデントが起きたことがあるようなので念の為変えておきましょう。

さいごに

今日は間を開けたので公開できました。
徐々に Hugo + GithubPages の方に引っ越しできるように色々と整理していきたいと思います。