Building a Static Blog with Hugo + GitHub Pages
- KeLin Cheng
- Tutorial
- October 17, 2024
Table of Contents
References: Reference 1, Reference 2
1. Preparation
1.1 Install Git
Git is a distributed version control system. Common commands: git init, git clone, git add, git commit, git push, git pull, git branch, git merge.
1.2 GitHub Account
Register a GitHub account. Create a repository named username.github.io for GitHub Pages.
1.3 Install Hugo
Hugo is a fast static site generator. Download the extended version for Windows.
2. Building
2.1 Environment Setup
Place the Hugo binary in a directory (e.g., C:\Hugo\bin) and add it to your system PATH.
2.2 Create Hugo Site
hugo new site mysite
cd mysite
2.3 Install Theme
Download and install a theme from the Hugo themes website (e.g., Blowfish, Congo).
3. Deployment
3.1 Build Static Assets
hugo
This generates a public/ directory with all static files.
3.2 Upload to GitHub
cd public
git init
git add .
git commit -m 'first commit'
git branch -M main
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main
3.3 GitHub Action Auto Deploy
Configure GitHub Personal Access Token (PAT) in Settings → Developer Settings. Set up the workflow in .github/workflows/deploy.yaml.
4. Notes
Create two repositories: one for static pages (username.github.io) and one for source code (e.g., Hugo.git).
References
- Hugo Official Documentation. https://gohugo.io/documentation/
- GitHub Pages Documentation. https://docs.github.com/en/pages
- Jimmy Song. Building GitHub Pages with Hugo. https://jimmysong.io/blog/building-github-pages-with-hugo/
Discussion Questions
- Now that GitHub Actions has simplified deployment to a single-repository workflow (source and output in the same repo), what are the remaining advantages and disadvantages of the two-repository approach described in this tutorial?
- Compared to other static site generators (Jekyll, Next.js, Astro), what specific design decisions make Hugo particularly well-suited for personal academic blogs? Under what circumstances would you choose a different tool?