Skip to content

Commit fad44d3

Browse files
author
Sebastian Heiden
committed
Add GitHub Pages deployment pipeline and build scripts
- Add GitHub Actions workflow for automatic deployment to GitHub Pages - Include Hugo 0.147.9 extended with SCSS support and minification - Add PowerShell and Bash build scripts for local development - Create comprehensive deployment documentation (DEPLOYMENT.md) - Configure workflow to trigger on main branch pushes - Support for submodules and Node.js dependencies - Automatic base URL configuration for GitHub Pages
1 parent 0f0f2ad commit fad44d3

4 files changed

Lines changed: 279 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Deploy Hugo site to GitHub Pages
2+
3+
on:
4+
# Trigger on push to main branch
5+
push:
6+
branches: [ main ]
7+
8+
# Allow manual trigger
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
# Default to bash
24+
defaults:
25+
run:
26+
shell: bash
27+
28+
jobs:
29+
# Build job
30+
build:
31+
runs-on: ubuntu-latest
32+
env:
33+
HUGO_VERSION: 0.147.9
34+
steps:
35+
- name: Install Hugo CLI
36+
run: |
37+
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
38+
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
39+
40+
- name: Install Dart Sass
41+
run: sudo snap install dart-sass
42+
43+
- name: Checkout
44+
uses: actions/checkout@v4
45+
with:
46+
submodules: recursive
47+
fetch-depth: 0
48+
49+
- name: Setup Pages
50+
id: pages
51+
uses: actions/configure-pages@v4
52+
53+
- name: Install Node.js dependencies
54+
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
55+
56+
- name: Build with Hugo
57+
env:
58+
HUGO_ENVIRONMENT: production
59+
HUGO_ENV: production
60+
run: |
61+
hugo \
62+
--gc \
63+
--minify \
64+
--baseURL "${{ steps.pages.outputs.base_url }}/"
65+
66+
- name: Upload artifact
67+
uses: actions/upload-pages-artifact@v3
68+
with:
69+
path: ./public
70+
71+
# Deployment job
72+
deploy:
73+
environment:
74+
name: github-pages
75+
url: ${{ steps.deployment.outputs.page_url }}
76+
runs-on: ubuntu-latest
77+
needs: build
78+
steps:
79+
- name: Deploy to GitHub Pages
80+
id: deployment
81+
uses: actions/deploy-pages@v4

‎DEPLOYMENT.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Hugo Site Deployment Guide
2+
3+
This guide explains how to deploy your Hugo site to GitHub Pages.
4+
5+
## 🚀 Automatic Deployment (Recommended)
6+
7+
### GitHub Actions Pipeline
8+
9+
The repository includes a GitHub Actions workflow (`.github/workflows/deploy.yml`) that automatically:
10+
11+
1. **Triggers on**: Push to `main` branch or manual dispatch
12+
2. **Builds the site** using Hugo 0.147.9 with extended features
13+
3. **Deploys to GitHub Pages** using the official GitHub Pages action
14+
15+
### Setup GitHub Pages
16+
17+
1. Go to your repository settings on GitHub
18+
2. Navigate to **Pages** section
19+
3. Under **Source**, select **GitHub Actions**
20+
4. The workflow will automatically run on your next push to `main`
21+
22+
### Workflow Features
23+
24+
- ✅ **Hugo Extended**: Supports SCSS and advanced features
25+
- ✅ **Minification**: Optimized for production
26+
- ✅ **Garbage Collection**: Removes unused files
27+
- ✅ **Base URL**: Automatically configured for GitHub Pages
28+
- ✅ **Submodules**: Handles theme submodules correctly
29+
- ✅ **Node.js**: Supports npm dependencies if needed
30+
31+
## 🔧 Manual Deployment
32+
33+
### Local Build
34+
35+
#### Windows (PowerShell)
36+
```powershell
37+
.\build.ps1
38+
```
39+
40+
#### Linux/macOS (Bash)
41+
```bash
42+
./build.sh
43+
```
44+
45+
#### Direct Hugo Commands
46+
```bash
47+
# Clean build
48+
rm -rf public/
49+
50+
# Build for production
51+
hugo --gc --minify --baseURL "https://yourusername.github.io/"
52+
53+
# The site will be in the public/ directory
54+
```
55+
56+
### Manual GitHub Pages Deployment
57+
58+
1. **Build locally** using one of the methods above
59+
2. **Create gh-pages branch** (if it doesn't exist):
60+
```bash
61+
git checkout --orphan gh-pages
62+
```
63+
3. **Copy public/ contents** to gh-pages branch
64+
4. **Push to gh-pages**:
65+
```bash
66+
git add .
67+
git commit -m "Deploy site"
68+
git push origin gh-pages
69+
```
70+
71+
## 📁 File Structure
72+
73+
### Source Files (tracked in git)
74+
```
75+
├── .github/workflows/deploy.yml # GitHub Actions workflow
76+
├── content/ # Markdown content
77+
├── static/ # Static assets
78+
├── layouts/ # Hugo layouts
79+
├── assets/ # Source assets
80+
├── hugo.toml # Hugo configuration
81+
└── themes/ # Hugo themes
82+
```
83+
84+
### Generated Files (ignored by git)
85+
```
86+
├── public/ # Generated site (deployed)
87+
├── resources/ # Hugo resources cache
88+
└── .hugo_build.lock # Hugo build lock
89+
```
90+
91+
## 🛠 Configuration
92+
93+
### Hugo Configuration (`hugo.toml`)
94+
The site is configured for GitHub Pages with:
95+
- Base URL: `https://yourusername.github.io/`
96+
- Unsafe HTML rendering enabled
97+
- Custom CSS and shortcodes
98+
- Utterances comments integration
99+
100+
### Build Options
101+
- `--gc`: Garbage collection for unused files
102+
- `--minify`: Minifies HTML, CSS, and JS
103+
- `--baseURL`: Sets the correct base URL for deployment
104+
105+
## 🐛 Troubleshooting
106+
107+
### Common Issues
108+
109+
1. **Images not loading**: Ensure images are in `static/` directory
110+
2. **CSS not applying**: Check asset paths in Hugo config
111+
3. **Build failures**: Check Hugo version compatibility
112+
4. **Theme issues**: Ensure themes are properly configured as submodules
113+
114+
### Debug Build
115+
```bash
116+
hugo --gc --minify --verbose --debug
117+
```
118+
119+
### Check Site Locally
120+
```bash
121+
hugo server --buildDrafts --buildFuture
122+
```
123+
124+
## 🔄 Deployment Process
125+
126+
1. **Make changes** to content, layouts, or configuration
127+
2. **Test locally** with `hugo server`
128+
3. **Commit and push** to `main` branch
129+
4. **GitHub Actions** automatically builds and deploys
130+
5. **Site is live** at `https://yourusername.github.io/`
131+
132+
The deployment typically takes 1-3 minutes to complete.
133+
134+
## 📊 Build Status
135+
136+
You can monitor the build status in the **Actions** tab of your GitHub repository. Each deployment will show:
137+
- Build time
138+
- Deploy time
139+
- Any errors or warnings
140+
- Link to the deployed site

‎build.ps1‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Hugo Build Script for Local Development
2+
# This script builds the Hugo site locally
3+
4+
Write-Host "🚀 Building Hugo site..." -ForegroundColor Green
5+
6+
# Clean previous build
7+
if (Test-Path "public") {
8+
Remove-Item -Recurse -Force "public"
9+
Write-Host "✅ Cleaned previous build" -ForegroundColor Yellow
10+
}
11+
12+
# Build the site
13+
try {
14+
hugo --gc --minify
15+
Write-Host "✅ Hugo build completed successfully!" -ForegroundColor Green
16+
17+
# Show build summary
18+
if (Test-Path "public") {
19+
$fileCount = (Get-ChildItem -Recurse "public" | Measure-Object).Count
20+
Write-Host "📊 Generated $fileCount files in public/ directory" -ForegroundColor Cyan
21+
}
22+
} catch {
23+
Write-Host "❌ Hugo build failed: $_" -ForegroundColor Red
24+
exit 1
25+
}
26+
27+
Write-Host "🎉 Build complete! You can now:" -ForegroundColor Green
28+
Write-Host " - Serve locally: hugo server" -ForegroundColor White
29+
Write-Host " - Deploy the public/ directory to your web server" -ForegroundColor White

‎build.sh‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/bin/bash
2+
# Hugo Build Script for Local Development
3+
# This script builds the Hugo site locally
4+
5+
set -e
6+
7+
echo "🚀 Building Hugo site..."
8+
9+
# Clean previous build
10+
if [ -d "public" ]; then
11+
rm -rf public
12+
echo "✅ Cleaned previous build"
13+
fi
14+
15+
# Build the site
16+
echo "🔨 Running Hugo build..."
17+
hugo --gc --minify
18+
19+
echo "✅ Hugo build completed successfully!"
20+
21+
# Show build summary
22+
if [ -d "public" ]; then
23+
file_count=$(find public -type f | wc -l)
24+
echo "📊 Generated $file_count files in public/ directory"
25+
fi
26+
27+
echo "🎉 Build complete! You can now:"
28+
echo " - Serve locally: hugo server"
29+
echo " - Deploy the public/ directory to your web server"

0 commit comments

Comments
 (0)