Hugo + GitHub Pages Starter

A minimal blog setup where the entire build happens in GitHub Actions. No local Hugo install required. Write markdown, push to main, your site is live.

Quick start

1. Use this template (click "Use this template" on GitHub, or fork it)
2. Enable GitHub Pages in your repo: Settings > Pages > Source: "GitHub Actions"
3. Push to main and your site deploys automatically

That's it. Your blog is live at https://yourusername.github.io/hugo-github-pages-starter/ (or your custom domain).

Customize

Edit hugo.toml:

• baseURL — your site URL
• title — site name
• params.author.name — your name
• params.home.profile — homepage title/subtitle
• params.social — your GitHub/LinkedIn/Twitter handles

Write a post

Create a file in content/posts/:

---
title: "My Post Title"
slug: "my-post-url"
date: 2026-05-15
draft: false
tags: ["topic1", "topic2"]
description: "Shows up in SEO and social cards."
---

Your content here. Standard markdown.

Push to main. Done.

Custom domain (optional)

1. Add a CNAME file to your repo root containing your domain (e.g., example.com)
2. At your DNS provider, add four A records pointing to GitHub's IPs:

   185.199.108.153
   185.199.109.153
   185.199.110.153
   185.199.111.153
   

3. Add a CNAME record: www → yourusername.github.io
4. In repo Settings > Pages, set your custom domain and check "Enforce HTTPS"

What's included

• Hugo config with LoveIt theme (as git submodule)
• GitHub Actions workflow that builds and deploys on push
• All actions pinned to commit SHAs (supply chain security)
• Minimal permissions (read-only except pages deployment)
• Page animations disabled
• Theme toggle hidden (light mode only)
• Share buttons disabled
• Custom CSS override without modifying the theme
• Post archetype template with SEO fields

Why this exists

Most Hugo tutorials assume you'll install Hugo locally, run hugo server, preview, then push. That's fine, but it means your blog only works from machines where you've set up the toolchain.

This starter makes the build entirely server-side. If you can edit a markdown file and push a commit, you can publish. Works from any machine, any editor, or even the GitHub web UI.

Analytics (optional)

The config includes a spot for GoatCounter (free, privacy-respecting, no cookies). Sign up, get your code, add it:

[params.analytics]
  enable = true
  [params.analytics.goatCounter]
    code = "your-code"

License

MIT. Use it however you want.