GitHub Pages is a free, reliable way to host static sites directly from a GitHub repository. Whether you’re showcasing a personal portfolio, publishing project documentation, or sharing a simple blog, GitHub Pages turns your code into a live website in minutes. This guide walks you through the entire process—from setting up a repository to troubleshooting common errors—so even if you’ve never touched a command line before, you’ll finish with a polished site on the internet.
What You’ll Need
- A GitHub account (free)
- Basic knowledge of HTML/CSS (optional but helpful)
- A local code editor (VS Code, Sublime, etc.)
- Git installed on your computer (or use GitHub Desktop)
- A static site ready to publish (index.html, CSS, assets)
Step 1: Create a New Repository
Log in to GitHub and click the “New” button on the repositories page. Give the repo a concise name—if you want a personal site, name it username.github.io (replace username with your GitHub handle). For project sites, any name works, e.g., my‑portfolio. Keep the repository public, add a short description, and click “Create repository.” This empty repo will host the files that GitHub Pages serves.
Step 2: Add Your Site Files
If you prefer the command line, clone the repo to your machine:
git clone https://github.com/username/repo-name.git
cd repo-nameCopy your static site files (at minimum an index.html) into the folder. Then stage, commit, and push:
git add .
git commit -m "Add initial site files"
git push origin mainIf you’re using GitHub Desktop, simply drag the files into the repository folder, then use the GUI to commit and push.
Step 3: Enable GitHub Pages
Navigate to the repository on GitHub, click the “Settings” tab, then scroll to the “Pages” section (under “Code and automation”). Choose the source branch—typically main—and the folder. For user/organization sites, select the root (/ (root)). For project sites, you can also use the /docs folder. Click “Save.” GitHub will generate a URL like https://username.github.io/ or https://username.github.io/repo-name/. The page may take a minute to appear.
Step 4: Verify the Deployment
Open the provided URL in a browser. If you see your index.html content, the deployment succeeded. If you encounter a 404 error, double‑check that the index.html file is in the selected branch/folder and that the Pages source is correctly configured. You can also view the build logs in the “Actions” tab for clues.
Step 5: Configure a Custom Domain (Optional)
Want a personalized URL like www.myportfolio.com? Purchase a domain from any registrar, then add a CNAME file to the root of your repository containing only the domain name:
myportfolio.comIn your domain’s DNS settings, create an A record pointing to GitHub’s IP addresses (185.199.108.153, .109, .110, .111) or a CNAME record pointing to username.github.io. After DNS propagation (usually minutes to a few hours), revisit your site using the custom domain. GitHub will automatically serve it via HTTPS.
Step 6: Keep Your Site Updated
Whenever you modify files locally, repeat the git add/commit/push cycle. GitHub Pages rebuilds automatically on each push. For quick edits, you can use the web editor: click the file in GitHub, press the pencil icon, make changes, and commit directly from the browser. Remember to commit to the same branch you configured for Pages.
Common Mistakes to Avoid
1 Wrong branch or folder selected: If GitHub Pages is set to gh-pages but you push to main, the site stays blank. Always match the source branch with where you push your files.
2 Missing index.html: GitHub Pages looks for an index.html at the root of the selected folder. Without it, visitors see a 404.
3 Case‑sensitivity issues: URLs on GitHub Pages are case‑sensitive. A link to Style.css will break if the file is named style.css.
4 Large assets: GitHub Pages enforces a 100 MB file size limit. Optimize images and bundle CSS/JS to stay well below this threshold.
5 Incorrect DNS for custom domains: Forgetting to add the CNAME file or using the wrong DNS record will prevent the custom domain from resolving.
Tips and Tricks
• Use a static site generator: Tools like Jekyll (built‑in to GitHub Pages), Hugo, or Eleventy let you write markdown and automatically generate HTML.
• Enable HTTPS: GitHub automatically provides a free SSL certificate for both default and custom domains—just toggle “Enforce HTTPS” in the Pages settings.
• Leverage GitHub Actions: Automate builds, linting, or image optimization before deployment with a simple workflow file.
• Cache busting: Append a query string (e.g., style.css?v=1.2) to assets when you update them, ensuring browsers load the newest version.
• Use a .nojekyll file: If you’re deploying assets that start with an underscore (e.g., _images), add an empty .nojekyll file to the root to bypass Jekyll processing.
Frequently Asked Questions
Can I host a dynamic site on GitHub Pages?
No. GitHub Pages only serves static files (HTML, CSS, JavaScript). For dynamic functionality, use client‑side JavaScript or connect to external APIs.
How long does a change take to appear?
Most pushes trigger a rebuild within a minute. DNS changes for custom domains can take up to 48 hours, though they usually propagate much faster.
Do I need to pay for a custom domain?
GitHub Pages itself is free, but the domain registration is a separate cost. Once you own the domain, linking it to GitHub Pages incurs no additional fees.
Conclusion
Deploying a static website with GitHub Pages is a straightforward, cost‑effective solution for beginners and seasoned developers alike. By following the six steps outlined above—creating a repo, adding files, enabling Pages, verifying the site, optionally configuring a custom domain, and maintaining updates—you’ll have a professional‑looking site live on the web with minimal hassle. Keep an eye on the common pitfalls, apply the tips, and you’ll enjoy a smooth, automated publishing workflow for all your future projects.
Photo by Jackson Sophat on Unsplash
