How Do I Use a Custom Domain with My GitHub Pages Blog

Why Add a Custom Domain to Your GitHub Pages Blog

While GitHub Pages provides a free .github.io subdomain, using your own custom domain makes your blog more professional and easier to remember. Whether it’s for branding, SEO, or credibility, connecting your domain is one of the most important steps to publishing your work seriously.

What You’ll Need

• A registered domain name (e.g., via Namecheap, GoDaddy, Cloudflare, etc.)
• A GitHub Pages site already published (such as using the Mediumish Jekyll theme)
• Access to your domain's DNS settings

Step-by-Step Guide to Setting Up a Custom Domain

1. Decide Between Apex Domain or Subdomain

You can use:

• Apex domain: yourdomain.com
• Subdomain: blog.yourdomain.com

Subdomains are usually easier to set up and propagate faster. Apex domains require more DNS configuration.

2. Update DNS Records

Go to your domain registrar’s DNS panel and update the following:

For Apex Domain

• Use A records pointing to GitHub Pages IPs:

185.199.108.153  
185.199.109.153  
185.199.110.153  
185.199.111.153

Remove any existing A records first. You may also need to configure ALIAS or ANAME if supported.

For Subdomain (Preferred)

• Use a CNAME record:

Type: CNAME  
Name: blog  
Value: yourusername.github.io

3. Create a CNAME File in Your GitHub Repo

Inside the root of your Jekyll blog repository (using Mediumish or any other theme), create a file named CNAME (all caps, no extension). Inside that file, write only your domain:

blog.yourdomain.com

Commit and push the change to GitHub:

git add CNAME  
git commit -m "Add custom domain"  
git push origin main

4. Configure GitHub Pages Settings

Go to your GitHub repo > Settings > Pages, and confirm your custom domain is recognized. GitHub will try to verify your DNS settings and may enable HTTPS automatically via Let's Encrypt.

5. Enable HTTPS (Optional But Recommended)

If GitHub shows HTTPS as available for your domain, check the box:

[✔] Enforce HTTPS

It might take a few minutes to issue the certificate.

Troubleshooting Common Issues

Domain Not Resolving

Check that your DNS changes have propagated. Use tools like DNSChecker.org to verify A and CNAME records globally.

404 or Theme Not Displaying

Make sure your Jekyll build has finished and GitHub Pages is not returning an error. Recheck if you pushed the CNAME file to the correct branch (usually main or gh-pages depending on your setup).

HTTPS Not Enabling

It may take up to 24 hours for GitHub to issue an SSL certificate. Also, make sure your domain provider doesn't block HTTP traffic by default. Services like Cloudflare or Namecheap usually work smoothly.

Using Cloudflare for DNS and Free CDN

If you want more control over your DNS, use Cloudflare as your nameserver. You can point your domain to GitHub Pages, enable HTTPS, and benefit from caching and speed optimizations.

How to Connect Cloudflare to GitHub Pages

• Change your domain nameservers to Cloudflare
• Create a CNAME or A record pointing to your GitHub username’s site
• Turn off proxying (orange cloud icon) at first to let GitHub detect your real domain
• Enable Full SSL mode once HTTPS is active

Maintaining Your Custom Domain Setup

Keep Your Domain Renewed

Domain expiration will cause your site to go offline. Enable auto-renew wherever possible.

Keep CNAME File Consistent

Do not remove or edit the CNAME file unless you change your domain. Its presence tells GitHub Pages which domain to use.

Verify HTTPS Occasionally

Even though certificates auto-renew, check your site occasionally to make sure there are no SSL or redirect errors.

Is a Custom Domain Really Necessary

Technically, no — GitHub Pages works perfectly fine with the default subdomain. But if you are:

• Building a professional portfolio
• Running a public-facing blog
• Trying to establish personal branding

Then using a custom domain is worth the small effort and cost. It’s often the difference between “just a dev blog” and “yourname.com”.

Summary of Best Practices

• Use subdomains (like blog.example.com) for easier DNS setup
• Create a CNAME file in your GitHub repo root
• Use GitHub Pages’ HTTPS and enforce it
• Check your site from multiple locations and devices
• Test DNS propagation using third-party tools

What to Do Next

Once your custom domain is active, consider:

• Setting up Google Search Console and submitting your sitemap
• Adding Open Graph and Twitter Card tags for social media previews
• Creating a favicon and custom 404 page
• Enabling analytics with Google Analytics or Plausible

Your blog is now fully hosted under your brand — on a reliable, free infrastructure provided by GitHub. That’s the power of static sites and custom domains.