How to Deploy Your Website for Free Using GitHub Pages: A Complete Beginner’s Guide
📘 Chapter 2: Setting Up Your GitHub Repository for Deployment
🧭 What You’ll Learn
By the end of this chapter, you’ll be able to:
- Create
a GitHub repository optimized for website hosting
- Upload
and manage your website files using GitHub
- Work
with Git locally to push updates
- Understand
directory structures and naming rules
- Prepare
your repository for GitHub Pages deployment
🚀 What is a GitHub
Repository?
A GitHub repository (repo) is a folder on GitHub
where you store and manage code and related project files. For GitHub Pages,
this repo will host your website's HTML, CSS, JavaScript, and image files.
🧱 Basic Requirements for
a GitHub Pages Repo
To successfully deploy a static site using GitHub Pages,
your repository must:
- Be public
(or Pro for private repos)
- Contain
an index.html file in the root or /docs folder
- Be
connected to your GitHub account
- Be
properly structured and cleanly committed
🔧 Step 1: Create a New
Repository on GitHub
🪜 Instructions:
- Go
to https://github.com
- Log
in with your account
- Click
the “+” icon → New repository
- Fill
in the details:
- Repository
name: my-website
- Description
(optional): “Personal website hosted on GitHub Pages”
- Visibility:
Public
- ✅
Check “Add a README file”
- Click
Create repository
✅ Pro Tips:
- Avoid
spaces in the repo name. Use hyphens or camelCase.
- Keep
it public if you want to use GitHub Pages for free.
📂 Step 2: Organize Your
Website Files
Make sure your website files follow this structure:
markdown
my-website/
│
├── index.html
├── about.html
├── contact.html
│
├── css/
│ └── styles.css
│
├── js/
│ └── scripts.js
│
└── images/
└── logo.png
index.html is essential—it acts as the homepage.
💻 Step 3: Upload Your
Files
You can upload files in two ways:
🅰️ Option A: Upload
Using GitHub UI
- Open
your repository
- Click
“Add file” → Upload files
- Drag
and drop your entire project (contents only, not the folder)
- Scroll
down and write a commit message: Initial website upload
- Click
Commit changes
🅱️ Option B: Upload
Using Git (Command Line)
If you have Git installed, follow these steps:
🔧 Initial Setup
bash
#
Clone the empty GitHub repo to your local system
git
clone https://github.com/yourusername/my-website.git
cd
my-website
#
Copy all your site files into this folder
cp
-r ../local-website/* .
#
Add, commit, and push
git
add .
git
commit -m "Initial commit"
git
push origin main
📝 Table: Git Commands
Overview
|
Command |
Description |
|
git init |
Initializes a new Git repository |
|
git clone <repo-url> |
Clones an
existing GitHub repo locally |
|
git add . |
Stages all files for
commit |
|
git commit -m "msg" |
Saves changes
to the local repo |
|
git push origin
main |
Uploads changes to
GitHub |
🔄 Step 4: Understand the
Branch & Folder Settings
GitHub Pages uses specific branches/folders to deploy your
site. You’ll configure this in the next chapter, but here’s a preview:
|
Deployment Type |
Source Setting |
Folder to Use |
|
Project site |
main branch, / root |
Place files at root |
|
Project site (docs) |
main branch,
/docs folder |
Place files
in /docs |
|
User site |
main branch, root only |
Repo must be named
username.github.io |
🗂️ Step 5: Use the /docs
Folder (Alternative Option)
If you prefer keeping your website files separate from other
project files, you can place them inside a /docs folder.
perl
my-website/
├── README.md
├── docs/
│ ├──
index.html
│ ├── css/
│ └── js/
Then, in GitHub Settings → Pages, select the /docs
folder as the source.
📘 Example HTML File
(index.html)
html
<!DOCTYPE
html>
<html>
<head>
<title>My Website</title>
<link rel="stylesheet"
href="css/styles.css">
</head>
<body>
<h1>Welcome to My Website</h1>
<p>This site is hosted using GitHub
Pages!</p>
</body>
</html>
🔒 Commit Messages and
Best Practices
When committing, always write meaningful messages:
bash
git commit -m "Added contact page and navigation
bar"
Good commit messages help you:
- Track
what changes were made and why
- Collaborate
with others more effectively
- Revert
issues with precision
🧼 Clean Repository
Checklist
|
Task |
✅ Done |
|
All files added |
✅ |
|
Unused files removed |
✅ |
|
index.html at root |
✅ |
|
CSS and JS in folders |
✅ |
|
Descriptive commit
messages |
✅ |
|
Public visibility enabled |
✅ |
🎁 Bonus: README and
.gitignore
📝 README.md
Give your repo a purpose:
markdown
#
My Website
This is my personal portfolio website hosted with GitHub
Pages.
🚫 .gitignore
Ignore IDE or OS-specific files:
bash
.DS_Store
node_modules/
*.log
🔍 Summary
In this chapter, we covered:
- How
to create and structure a GitHub repository
- How
to upload website files (via UI and Git CLI)
- The
purpose of index.html and folder structure
- Using
/docs as an optional deployment folder
- Version
control via Git and commit best practices
Your repository is now ready for deployment. In the next
chapter, we’ll activate GitHub Pages and bring your website live to the
world!
FAQs
❓ 1. What is GitHub Pages and how does it work?
Answer:
GitHub Pages is a free hosting service by GitHub that allows you to publish
static websites directly from a GitHub repository. It works by serving the
HTML, CSS, JS, and other static files from your repo to a web URL like
https://yourusername.github.io/.
❓ 2. Is GitHub Pages really free to use?
Answer:
Yes, GitHub Pages is completely free. There are no hidden fees, and you can
host as many static sites as you want as long as your repository is public.
Private repo hosting is available with GitHub Pro.
❓ 3. What kind of websites can I host on GitHub Pages?
Answer:
You can host static websites, such as portfolios, documentation, blogs,
resumes, and simple landing pages. It does not support server-side languages
like PHP, Python, or databases.
❓ 4. What file should my website start with for GitHub Pages to work?
Answer:
Your site should have an index.html file in the root directory (or /docs if
using that folder). This acts as the homepage for your site.
❓ 5. How long does it take for my GitHub Pages site to go live?
Answer:
Typically, your site is live within 30 seconds to 2 minutes after
enabling GitHub Pages. However, DNS changes (like custom domains) may take up
to 24 hours.
❓ 6. Can I use a custom domain with GitHub Pages?
Answer:
Yes! You can map a custom domain by updating your DNS settings and adding a
CNAME file to your repository with your domain name in it (e.g.,
www.yoursite.com).
❓ 7. Can I use GitHub Pages with frameworks like React or Vue?
Answer:
Yes, you can build your project and push the static build/ folder to
your GitHub repo. Some projects use the /docs folder for this or deploy using
GitHub Actions for automation.
❓ 8. How do I fix broken links or missing styles/scripts?
Answer:
Check if your file paths are correct and relative (e.g., ./style.css instead of
/style.css). Also, make sure your files are in the correct directories and
committed to the repo.
❓ 9. Can I use GitHub Pages for private projects?
Answer:
You can only host public repos for free with GitHub Pages. For private repo
hosting, you’ll need a GitHub Pro plan or use GitHub Actions to deploy
elsewhere (like Netlify).
❓ 10. What are some alternatives to GitHub Pages?
Answer:
Other free static hosting options include:
- Netlify
- Vercel
- Firebase
Hosting
- Cloudflare Pages
These services offer more flexibility for dynamic apps,
CI/CD, and advanced routing.
Comments(0)