Use this guide when you have built a simple static site, such as a portfolio or a hobby page, and want it online without paying for hosting. You need a free GitHub account, your site files with an index.html page and, ideally, Git installed.
Step by step
Get your files ready
Make sure your home page is called index.html and sits in the top level of your project folder, with other pages, CSS and images alongside or in subfolders. Use relative links, such as images/photo.jpg, rather than paths on your own computer. Open index.html in a browser to check everything works locally.
Create a repository
Sign in to GitHub and create a new public repository with a short, clear name. On a free account, GitHub Pages works with public repositories, so do not include anything private. Avoid putting passwords, personal documents or API keys in the files.
Upload your site
Push your files with Git from your project folder, or use the upload option on the repository page for a first attempt. Check that index.html appears in the main list of files, not inside an extra folder. Commit with a short message such as 'First version of site'.
Turn on GitHub Pages
In the repository, open Settings, then Pages. Choose to deploy from a branch, select your main branch and the root folder, and save. After a few minutes GitHub shows the address of your live site, usually your username followed by github.io and the repository name.
Test the live site
Open the address in your browser and on your phone, and click every link and image. Broken images are often caused by different capital letters in file names, because the web server treats Photo.jpg and photo.jpg as different files. Fix issues locally, then push the changes again.
Update it safely
Make and test changes on your computer first, then commit and push them; the live site updates automatically after a short delay. Keep commits small with clear messages so you can go back if something breaks. If you later want your own domain name, follow GitHub's custom domain instructions and your domain provider's DNS settings.
Ready-to-use checklist
- Home page named index.html
- Relative links used
- Site tested locally
- Public repository created
- No private data in the files
- Pages turned on in Settings
- Live site checked on a phone
- Update process tested with a small change
Practical tips
- Use lower-case file names with hyphens instead of spaces to avoid broken links.
- Add a meta viewport tag in the head of each page so the site displays properly on mobiles.
- Hard refresh your browser or try a private window if you cannot see your latest changes.
Common problems
The site shows a 404 page.
Check that index.html is at the top level of the branch and folder you chose in the Pages settings. Wait a few minutes after changing settings, then try again.
The page loads but has no styling or images.
Your links probably point to files on your own computer or use the wrong capital letters. Use relative paths that match the file names exactly.
Your changes do not appear on the live site.
Confirm the commit was pushed to the branch Pages uses, and check the Actions or deployments section in the repository for errors. Then hard refresh the browser.
This guide gives general information, not personal legal, financial or medical advice. Rules and prices change, so check the current position with the official service before acting.
This guide is free. Unlock all ABCDayZ guides from £3.99 – one payment, no automatic renewal.