GitHub Pages is one of the easiest ways to publish a website online for free. It is great for portfolios, landing pages, documentation, small business websites, and simple frontend projects. I use them all the time as all my code is stored on GitHub.
In this tutorial, I will show you how to host your website using GitHub Pages step by step.
What is GitHub Pages?
GitHub Pages is a free hosting service from GitHub that lets you publish static websites directly from a GitHub repository.
You can use it to host websites built with:
- HTML
- CSS
- JavaScript/ TypeScript
- React
- Vue
- Documentation sites
- Portfolio websites
GitHub Pages is best for static websites. That means it does not run backend code like Java, Spring Boot, PHP, or Node.js servers. However, it is perfect for frontend projects. For my bigger projects, I still use GitHub Pages for the front-end and host the back-end somewhere else.
Step 1: Create a GitHub Account
After logging in to GitHub:
- Click the New button to create a new repository.
- Give your repository a name.
- Make the repository Public.
- Click Create repository.
For example, you can name it:
deividas-strole-website
Your website URL will look something like this:
https://your-username.github.io/deividas-strole-website/
Step 3: Add Your Website Files
Your project should include at least an index.html file.
Example project structure:
deividas-strole-website/
├── index.html
├── style.css
└── script.js
Here is a simple example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Deividas Strole Website</title>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<h1>Hello from GitHub Pages!</h1>
<p>This website is hosted for free using GitHub Pages.</p>
<script src="script.js"></script>
</body>
</html>
You can upload the files directly through GitHub, or you can push them using Git.
Step 4: Push Your Files to GitHub
If you are using Git from your computer, open your terminal inside your project folder and run:
git init
git add .
git commit -m "Initial website files"
git branch -M main
git remote add origin https://github.com/your-username/deividas-strole-website.git
git push -u origin main
Replace:
your-username
with your GitHub username.
Also replace:
deividas-strole-website
with your repository name.
Step 5: Enable GitHub Pages
Now go to your repository on GitHub.
Then follow these steps:
- Click Settings
- Click Pages in the left menu
- Under Build and deployment, choose Deploy from a branch
- Select the branch: main
- Select the folder: /root
- Click Save
GitHub will now build and publish your website.
Step 6: Open Your Live Website
After a short moment, GitHub will show you your live website URL.
It will look like this:
https://your-username.github.io/deividas-strole-website/
Open that link in your browser, and your website should be live.
Congratulations! Your website is now hosted for free.
Important: Use the Correct File Paths
When using GitHub Pages, file paths are very important.
For example, if your CSS file is in the same folder as your HTML file, use:
<link rel="stylesheet" href="style.css" />
If your image is inside an images folder, use:
<img src="images/photo.jpg" alt="My photo" />
Avoid using paths that only work on your local computer, like:
C:/Users/YourName/Desktop/project/image.jpg
That will not work online.
Common GitHub Pages Problems
Website Shows a 404 Page
This usually means GitHub Pages is not enabled correctly, or your project does not have an index.html file.
Make sure your main page is named exactly:
index.html
Not:
home.html
Index.html
index.htm
The file name must be correct.
CSS or Images Are Not Loading
Check your file paths carefully.
For example, this will only work if the image is inside an images folder:
<img src="images/logo.png" alt="Logo" />
Also make sure the file names match exactly. GitHub Pages is case-sensitive.
This means these are different:
logo.png
Logo.png
LOGO.png
Changes Are Not Showing
Sometimes GitHub Pages takes a minute to update.
You can also try:
- Refreshing the page
- Clearing your browser cache
- Checking the GitHub Pages deployment status
- Making sure your latest changes were pushed to GitHub
Can You Use a Custom Domain?
Yes. GitHub Pages allows you to connect a custom domain.
For example, instead of using:
https://your-username.github.io/deividas-strole-website/
You can use something like:
https://deividasstrole.com
You need to buy a domain separately and update your DNS settings.
When Should You Use GitHub Pages?
GitHub Pages is a good choice for:
- Portfolio websites
- Resume websites
- Landing pages
- Project demos
- Documentation
- Simple business websites
- Frontend practice projects
It is not the best choice for websites that need a backend server, database, login system, or server-side processing.
For those, you may need services like Render, Railway, Vercel, Netlify, AWS, or a VPS.
Final Thoughts
GitHub Pages is a simple and free way to publish your website online.
If you are learning web development, building a portfolio, or sharing frontend projects, GitHub Pages is one of the best tools to start with.
You do not need complicated hosting or paid servers. You only need a GitHub account, your website files, and a few minutes to publish your project.
Happy coding!
About the Author
Deividas Strole is a Full-Stack Developer based in California, specializing in Java, Spring Boot, JavaScript, React, SQL, and AI-driven development. He writes about software engineering, modern full-stack development, and digital marketing strategies.
About the Author
Deividas Strole is a Full-Stack Developer based in California, specializing in Java, Spring Boot, JavaScript, React, SQL, and AI-driven development. He writes about software engineering, modern full-stack development, and digital marketing strategies.
Connect with me:
