Today I learned how to set up GitHub Pages with a custom subdomain, which I used for my SpeakEasy documentation site.
This builds on the basic GitHub Pages setup - make sure you have that working first!
The Goal
Host a GitHub Pages site at speakeasy.arach.dev instead of the default username.github.io/repo-name URL.
Step-by-Step Setup
1. Configure GitHub Pages
In your repository:
- Go to Settings → Pages
- Set Source to “Deploy from a branch”
- Choose your branch (usually
mainorgh-pages)
2. Add Custom Domain
- In the Custom domain field, enter:
speakeasy.arach.dev - This creates a
CNAMEfile in your repository root
3. Configure DNS Records
In your domain’s DNS settings (I use Cloudflare), add a CNAME record:
Type: CNAME
Name: speakeasy
Target: arach.github.io
Proxy: DNS only (gray cloud)4. Wait for DNS Propagation
- Can take up to 24 hours
- Check with:
dig speakeasy.arach.dev - Should return your GitHub Pages IP
5. Enable HTTPS
- Back in GitHub Pages settings
- Check Enforce HTTPS (may take a few minutes to become available)
Key Gotchas
- Don’t proxy through Cloudflare initially - use “DNS only” mode
- The CNAME target is your username.github.io, not the full repo URL
- GitHub automatically handles the redirect from your custom domain to the right repository
Result
Your site is now live at https://speakeasy.arach.dev with automatic HTTPS! 🎉
This setup is perfect for documentation sites, project demos, or any static content you want on a branded subdomain.