If you have a simple website built with HTML, CSS, and JavaScript (or generated output from a static site generator), you can host it completely for free using GitHub Pages. No server management, no backend, no hosting bills. In this article, you’ll learn how to get your static site online using GitHub Pages, configure a custom domain, optimize for SEO, and maintain your site efficiently.
What Is GitHub Pages?
GitHub Pages is a static site hosting service offered by GitHub. It takes the static files (HTML, CSS, JavaScript) from a repository and publishes them as a website. It supports optional build steps (such as using Jekyll) and enables global delivery via HTTPS.
There are two main types of GitHub Pages sites:
- User / organization site — your repository must be named username.github.io, and the site is published at https://username.github.io.
- Project site — any repository can publish a site under https://username.github.io/repository-name.
GitHub Pages is available for public repositories on GitHub Free, and supports HTTPS, custom domains, and automatic build/deployment from branches.
Why Choose GitHub Pages?
- It’s free for static content.
- Easy versioning and deployment via Git.
- Built-in support for Jekyll (Markdown + templating).
- You can push updates and have them go live automatically.
- Ability to use your own domain with HTTPS.
- Great choice for portfolios, documentation, blogs (static), project sites, and marketing pages.
However, note that GitHub Pages only supports static content — you cannot run server-side code (e.g. PHP, Node, Python backend) or databases natively.
Step-by-Step: Publishing Your Static Website
1. Create (or use) a GitHub account
If you don’t already have one, sign up on GitHub and verify your email.
2. Create a repository for your site
For a user/organization site, name the repo exactly username.github.io (replace username with your GitHub username).
For a project site, choose any repository name.
Make the repository public (free GitHub Pages requires public repos for publishing).
Optionally initialize with a README.md.
3. Add your website files
You need at minimum an index.html (or index.md) file in the root (or publishing folder). You can use:
- Web interface: upload your HTML, CSS, JS, images via GitHub’s “Add file → Upload files”.
- Local Git: clone the repository, add your site files, commit, and push.
Ensure your internal links are relative, and your assets (CSS, JS, images) are correctly referenced.
4. Enable GitHub Pages in settings
Go to your repository’s Settings → Pages (or “Code and automation → Pages”).
Under “Build and deployment”, select a branch (commonly main or master) and choose the folder (/ root or a subfolder like /docs).
Save that configuration.
Wait a few minutes for GitHub to build and publish your site.
Your site will be available at https://username.github.io or https://username.github.io/repo-name.
5. Use a custom domain (optional)
To use your own domain (e.g. www.example.com), do the following:
In your repository’s Pages settings, add the custom domain (e.g. www.example.com). GitHub will expect a file CNAME containing that domain in the publishing branch.
In your DNS settings:
- For a subdomain (www), point a CNAME record to username.github.io.
- For a root/apex domain, add A records pointing to GitHub Pages’ IP addresses (e.g. 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153).
Wait for DNS propagation (can take minutes to hours).
In GitHub settings, enable “Enforce HTTPS” (if available) for your custom domain.
6. Update and maintain your site
Whenever you want to change content:
- Edit files locally or via GitHub interface.
- Commit and push changes to the publishing branch.
GitHub Pages will automatically rebuild and republish your site (usually within a few minutes).
If you are using a static site generator (like Jekyll, Hugo, etc.), you may build locally and push the generated output, or use a GitHub Actions workflow to build and deploy.
7. Disable Jekyll (if needed)
If you don’t want GitHub to process your site with Jekyll (for example, if you're using another build tool), you can add an empty file named .nojekyll in the root of your publishing branch to disable Jekyll processing.
SEO & Best Practice Tips
- Give each page a unique title and meta description.
- Use proper header tags (H1, H2, H3) semantically.
- Ensure your site is mobile-responsive.
- Use alt text on images for accessibility and SEO.