Host an HTML Website for Free on GitHub Pages
Publish an HTML template on GitHub Pages for free: create a repository, turn on Pages, add a custom domain with HTTPS, and know the size and usage limits.
By UndieGravity, , 1 min read
GitHub Pages serves static files (HTML, CSS, JavaScript, and images) straight from a repository, for free. It is a great home for a portfolio, a project page, or a one page site built from an HTML template.
1. Put the site in a repository
- Create a new public repository on GitHub.
- Upload your template files with Add file, Upload files, or push them with Git.
- Make sure
index.htmlis in the root of the repository (or in adocsfolder).
2. Turn on Pages
- Open the repository's Settings, Pages.
- Under Build and deployment, choose Deploy from a branch.
- Select the
mainbranch and the/ (root)folder, then save.
After a minute your site is live at https://USERNAME.github.io/REPOSITORY/. A repository named USERNAME.github.io is published at the root address instead; each account gets one of those.
3. Use relative paths
Because project sites live under /REPOSITORY/, a link to /style.css points at the wrong place. Use relative paths such as style.css or ./images/photo.webp, and the site works both locally and on Pages.
4. Add a custom domain
- In Settings, Pages, enter your domain, for example
www.example.com. - At your registrar, add a
CNAMErecord forwwwpointing toUSERNAME.github.io. - For the root domain, add the
Arecords listed in GitHub's documentation. - When the check passes, tick Enforce HTTPS.
Limits to know
- Published sites can be at most 1 GB.
- There is a soft bandwidth limit of 100 GB per month.
- Deployments time out after 10 minutes.
- GitHub's terms say Pages is not intended as free hosting for an online business or ecommerce store. For a shop, use a host built for it.
Next.js and React on Pages
Pages serves static files only. A React (Vite) build works as is. A Next.js site works with output: "export" and the right basePath; features that need a server, such as Server Actions, do not.