Why GitHub Pages is the lazy person hero of free hosting
If you want free hosting for a static site and you like things that do not cost money or cause heartburn then GitHub Pages is your friend. It serves HTML CSS and assets straight from a repository and it plays nicely with static site generators like Jekyll. This guide shows the tidy path from files on your machine to a live URL without needing to sell a kidney.
Pick the right repo name for the kind of site you want
- User page use a repo named username.github.io and your site will live at https and friendly username.github.io
- Project page any repo name works and the site will appear at username.github.io/repo-name
Add your site files
Put an index.html
at the repository root and GitHub will hand it out as the landing page. If you prefer generators Jekyll works out of the box and other static site tools are welcome. If you need to skip Jekyll add a file named .nojekyll
to the root.
Quick and painless Git commands
If you enjoy typing things into a terminal try this sequence on a new project repository
git init
git add .
git commit -m 'first commit'
git branch -M main
git remote add origin https://github.com/username/repo.git
git push -u origin main
If you are allergic to the command line you can also upload files from the GitHub web interface with drag and drop.
Turn on Pages in repository settings
Open Settings and find the GitHub Pages section. Choose the main
branch and the root folder as the source. GitHub will publish a URL and the site often appears within a minute or two. If the web UI shows an address you can visit it and pretend you made something brilliant.
Use a custom domain if you want to impress
Create a file named CNAME
at the repository root with your custom domain on a single line. Then update DNS at your registrar. For apex domains add A records with the GitHub Pages IPs 185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153. For subdomains add a CNAME record that points to username.github.io. DNS propagation takes some time so be patient or go make coffee.
After the domain verifies enable HTTPS from the Pages settings so your site looks official and secure.
Deploy notes for static generators
If you use Jekyll or another static generator build the site locally and push the generated files to the branch you selected for Pages. For many setups you can commit the source and the generated site to the same repo using a build script or CI pipeline to automate the deploy step.
Troubleshooting checklist that actually helps
- Confirm there is an
index.html
at the chosen source root - Make sure the correct branch is selected in Pages settings
- If a custom domain is not resolving check the CNAME file and the registrar DNS records
- Use a DNS propagation checker to verify values if the site is still not reachable
- Clear the browser cache or try a private window before assuming the internet is broken
Wrap up and where to go next
You now have the essentials to deploy a free static site with GitHub Pages. You learned repo naming for user versus project pages adding files using Git or the web UI enabling Pages and wiring up a custom domain with DNS and HTTPS. Next steps include automating deploys with GitHub Actions adding a static site generator pipeline and styling that landing page so it actually looks like you tried.
If anything goes sideways come back to these steps and check the obvious items first. And remember free hosting is great until you forget to renew the domain or break something spectacularly clever.