A modern Hugo-powered blog with automated GitHub Pages deployment using GitHub Actions. This repository showcases best practices for static site generation, continuous deployment, and clean documentation.
✅ Status: Fully automated deployment pipeline configured and working correctly.
🌐 Live Site: https://sehheiden.github.io
- Make Changes: Edit content in
content/or update configurations as needed. - Test Locally: Run
hugo server -Dto preview onhttp://localhost:1313. - Commit Changes: Use Git -
git add .,git commit -m "message",git push. - Deploy: Automatic via GitHub Actions or manually using provided scripts.
- Automated Deployment: GitHub Actions pipeline with Hugo Extended support
- Single Branch Workflow: Streamlined deployment from
mainbranch only - Build Optimization: Minification, garbage collection, and asset optimization
- Fast Deployment: Typically completes in 1-3 minutes
- Dependency Management: Dependabot for automated GitHub Actions updates
- Pre-commit Hooks: Automatic cleanup of generated files
- Cross-platform Build Scripts: PowerShell (Windows) and Bash (Unix) support
- Hot Reload: Live preview with
hugo server - Submodule Support: Automatic handling of theme dependencies
- Responsive Design: Mobile-first approach
- Performance Optimized: Minified assets and optimized loading
- SEO Ready: Meta tags and structured data support
- Comment System: Utterances integration for GitHub-based discussions
├── .github/
│ ├── workflows/deploy.yml # GitHub Actions CI/CD pipeline
│ └── dependabot.yml # Dependency management
├── content/ # Markdown content and blog posts
│ └── posts/ # Blog articles
├── static/ # Static assets (images, files)
├── layouts/ # Custom Hugo templates
├── assets/ # Source assets (SCSS, JS)
├── themes/ # Hugo themes (as submodules)
├── hugo.toml # Hugo configuration
├── build.ps1 # Windows build script
├── build.sh # Unix build script
└── README.md # This comprehensive guide
public/- Built static site (deployed)resources/- Hugo cache and processed assets.hugo_build.lock- Hugo build lock file
The site is configured for GitHub Pages with:
- Base URL:
https://seheheiden.github.io/ - Unsafe HTML rendering enabled (for rich content)
- Custom CSS and shortcodes support
- Utterances comments integration
- European timezone settings
| Component | Version/Details |
|---|---|
| Hugo | 0.147.9 Extended |
| Node.js | Latest LTS (for npm dependencies) |
| Dart Sass | Latest (via snap) |
| Deployment | GitHub Actions + GitHub Pages (workflow mode) |
| Build Time | ~30-60 seconds |
| Deploy Time | ~1-3 minutes total |
| Pages Source | GitHub Actions (not branch deployment) |
The repository includes a GitHub Actions workflow that automatically:
- Triggers on: Push to
mainbranch or manual dispatch - Builds the site using Hugo 0.147.9 with extended features
- Deploys to GitHub Pages using the official GitHub Pages action
- ✅ Hugo Extended: Supports SCSS and advanced features
- ✅ Minification: Optimized for production
- ✅ Garbage Collection: Removes unused files
- ✅ Base URL: Automatically configured for GitHub Pages
- ✅ Submodules: Handles theme submodules correctly
- ✅ Node.js: Supports npm dependencies if needed
- Windows: Run
./build.ps1 - Linux/macOS: Run
./build.sh
# Clean build
rm -rf public/
# Build for production
hugo --gc --minify --baseURL "https://seheheiden.github.io/"
# The site will be in the public/ directory# Start development server with drafts
hugo server -D
# With future posts and drafts
hugo server --buildDrafts --buildFutureImportant: GitHub Pages must be configured to use GitHub Actions, not branch deployment.
- Go to your repository settings on GitHub
- Navigate to Pages section
- Under Source, select GitHub Actions (not "Deploy from a branch")
- Simply push to
mainto automatically deploy via GitHub Actions
Verification: Check that your Pages configuration shows "build_type": "workflow":
gh api repos/sehHeiden/sehHeiden.github.io/pages# Create a new blog post
hugo new posts/my-new-post.md
# Start development server
hugo server -D
# Build for production
hugo --gc --minify# Make your changes
git add .
git commit -m "Add new post: My Amazing Article"
git push origin main
# GitHub Actions will automatically build and deploy!- Website shows README instead of blog: This happens when GitHub Pages is set to "Deploy from a branch" instead of "GitHub Actions". Fix by changing Pages source to "GitHub Actions" in repository settings.
- CSS/JS Issues: Check paths and ensure assets are in
static/directory - Build Errors: Run
hugo --verbose --debugfor detailed diagnostics - Deployment Errors: Check GitHub Actions logs in the "Actions" tab
- Theme Issues: Ensure submodules are properly initialized with
git submodule update --init --recursive - Images not loading: Ensure images are in
static/directory
Problem: Site shows repository README instead of Hugo blog Solution:
- Go to repository Settings → Pages
- Change Source from "Deploy from a branch" to "GitHub Actions"
- Or use CLI:
gh api --method PUT repos/sehHeiden/sehHeiden.github.io/pages --field build_type=workflow --field source[branch]=main --field source[path]=/
Verify: Check configuration with:
gh api repos/sehHeiden/sehHeiden.github.io/pagesEnsure "build_type": "workflow" (not "legacy")
-
Monitor Deployments:
gh run list --workflow="deploy.yml" --limit 5 -
View Deployment Logs:
gh run view [RUN_ID] --log
-
Debug Build Locally:
hugo --gc --minify --verbose --debug
Monitor the build status in the Actions tab of your GitHub repository. Each deployment shows:
- Build time (~30-60 seconds)
- Deploy time (~1-3 minutes total)
- Any errors or warnings
- Link to the deployed site
- 🚀 GitHub Actions Workflow: CI/CD pipeline configuration
- 🤖 Dependabot Config: Automated dependency updates
- 🌐 Live Site: See the blog in action
- 📊 Hugo Documentation: Official Hugo docs
- 🔧 GitHub Pages Documentation: GitHub Pages setup guide
Your site is configured for effortless deployment. Focus on creating great content while the automation handles all the technical details. Happy writing! ✍️