Last updated on July 27, 2025

Hugo 를 사용하여 Github Pages를 생성해 보자 (Mac 환경에서).

0 Prerequisites

1 Github Pages

Github에서 <username>.github.io 로 repository 생성

Terminal에서 hugo site 생성 후 위 repo와 연동

hugo new site <username>.github.io -f yml
cd <username>.github.io
git init
git remote add origin git@github.com:<username>/<username>.github.io
git branch -M main

제일 star이 많은 Hugo PaperMod theme 사용

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive

(추가) 지금 당장은 필요 없지만, 추후에 theme을 update하고 싶다면, 아래 명령어를 통해 가능하다:

git submodule update --remote --merge

./config.yml 수정:

baseURL: https://<username>.github.io/
languageCode: en-us
title: title
theme: "PaperMod"

.github/workflows/gh-pages.yml 생성 후 아래 내용 추가:

name: GitHub Pages

on:
  push:
    branches:
      - main  # Trigger deployment only on push to main
  workflow_dispatch:  # Optional: allow manual trigger

permissions:
  contents: write  # Required for actions-gh-pages to deploy

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Needed if your theme is a submodule
          fetch-depth: 0         # Needed for .GitInfo

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true  # Required for SCSS/SASS support in themes like PaperMod

      - name: Build website
        run: hugo --minify

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

해당 Github Actions을 사용하면 main branch로 push하면 자동으로 generated content을 gh-pages branch로 commit.

git add .
git commit -m "..."
git push -u origin main

실제로 main branch로 push하면 gh-pages branch가 생성되어 있다.

해당 repo에서 source branch를 gh-pages로 설정하면 끝.