hosting github pages |Video upload date:  · Duration: PT8M55S  · Language: EN

Quick guide to host a static site on GitHub Pages from repo setup to custom domain and publishing

Step by step guide to hosting a static site on GitHub Pages with a custom domain

So you want free web hosting and a shred of dignity left over. GitHub Pages will host your static site from a repo and spare you the invoice spam. This guide walks through creating a repo, adding files, choosing a publishing source, hooking up a custom domain, and verifying the site is live. It is practical and mildly judgmental.

Prepare your repository

Create a new public repository on GitHub or reuse one you already ruined. Public repos get free GitHub Pages hosting, which means free static site hosting without billing drama. If you like living dangerously keep it public.

  1. Add your site files. The simplest option is an index.html at the repository root or inside a docs folder.
  2. From your local machine run these git commands to start tracking and push to GitHub
git init
git add .
git commit -m "launch"
git branch -M main
git remote add origin git@github.com:youruser/yourrepo.git
git push -u origin main

If you prefer a dedicated branch for the published site use gh-pages. For that use

git checkout -b gh-pages
git push -u origin gh-pages

Choose the publishing source in Pages settings

Open the repository settings and look for Pages. Pick the branch to publish from and set the folder to root or docs depending on where index.html lives. Common branches are main or gh-pages. Once selected GitHub Pages will try to build and publish the site.

Optional custom domain and DNS

If you want a custom domain add a plain text CNAME file to the publishing branch containing your domain name like

www.example.com

Then update DNS records at your registrar. For apex domains add the A records GitHub suggests. For subdomains use a CNAME record pointing to your GitHub Pages hostname. DNS changes can take a few minutes or a few hours depending on how cranky your registrar is.

Publish and verify

After saving the publishing source the Pages system will build and publish the site. The Pages settings will show a live site URL or a green check when everything is healthy. If you see an error check that index.html is where you think it is, confirm the publishing branch, and review commit history before blaming your router.

For security and fewer mixed content headaches enable Enforce HTTPS in Pages. That gives you HTTPS for your site once DNS and certificate issuance finish.

Troubleshooting and common gotchas

  • 404 errors usually mean wrong branch or missing index file in the chosen folder.
  • Custom domain troubles often come from DNS records not matching GitHub guidance or propagation delays.
  • If you use a docs folder confirm the Pages source is set to that folder and not root.
  • Remember that GitHub Pages is for static sites. If your app needs server side code use another hosting option.

Quick checklist for launch

  • Create or reuse a public repo
  • Place index.html at root or in docs
  • Push the publishing branch to GitHub
  • Pick the branch or folder in Pages settings
  • Add a CNAME file and update DNS for a custom domain if you want one
  • Enable Enforce HTTPS once the site is live

Follow these steps and your static site will be live on GitHub Pages without hiring a wizard. If something breaks consult the Pages guide on GitHub or enjoy blaming the internet gods for a bit before fixing it.

I know how you can get Azure Certified, Google Cloud Certified and AWS Certified. It's a cool certification exam simulator site called certificationexams.pro. Check it out, and tell them Cameron sent ya!