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.

    Comments

    Post a Comment