How to Make a GitHub Website- Complete Tutorial

What You're Getting Into

GitHub Pages is free web hosting. That's the bottom line. You get a website up and running without paying a dime for hosting. The catch? Your content lives in a public repository (unless you pay for GitHub Pro), and you get limited customization options compared to traditional hosting.

This guide cuts through the noise. By the end, you'll have a live website running on github.io.

Why Use GitHub Pages?

Here's the deal:

Perfect for portfolios, documentation, project pages, or personal blogs. Not ideal for e-commerce or anything requiring server-side processing.

What You Need Before Starting

Step 1: Create Your GitHub Account

Head to github.com and sign up. Pick a username you'll be okay with because this becomes part of your URL: yourusername.github.io.

Choose your username carefully. This isn't easily changed later.

Step 2: Create a New Repository

After logging in:

  1. Click the + button in the top-right corner
  2. Select "New repository"
  3. Name it exactly: yourusername.github.io (replace "yourusername" with your actual GitHub username)
  4. Set it to Public (required for free hosting)
  5. Check "Add a README file"
  6. Click "Create repository"

That's it. Your repository exists. Now you need to put files in it.

Step 3: Create Your First File

You have two options here. I'll show you both.

Option A: Through the GitHub Web Interface

This works if you're not comfortable with command line tools.

  1. Inside your new repository, click Add file → Create new file
  2. Name it index.html
  3. Paste this basic HTML:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Site</title>
</head>
<body>
    <h1>Hello, World</h1>
    <p>My site is live!</p>
</body>
</html>
  1. Scroll down, add a commit message like "Add index.html"
  2. Click Commit new file

Option B: Using Git on Your Computer

If you're comfortable with the terminal, this approach scales better for larger projects.

# Clone the repository to your computer
git clone https://github.com/yourusername/yourusername.github.io.git

# Navigate into the folder
cd yourusername.github.io

# Create your HTML file
echo "<!DOCTYPE html>
<html>
<body>
<h1>Hello, World</h1>
</body>
</html>" > index.html

# Add, commit, and push
git add index.html
git commit -m "Add index.html"
git push origin main

Use this method if you plan to update your site regularly. It's faster once set up.

Step 4: Enable GitHub Pages

Here's where people get stuck. GitHub Pages doesn't auto-enable.

  1. Go to your repository's Settings tab
  2. Scroll down to Pages (usually in the left sidebar under "Code and automation")
  3. Under "Source", click the dropdown and select Deploy from a branch
  4. Next dropdown: select main
  5. Next dropdown: select / (root)
  6. Click Save

Wait 1-2 minutes. Your site goes live at https://yourusername.github.io

Step 5: Verify It's Working

Open a new browser tab. Type your URL. You should see your HTML rendered as a webpage.

If you see a 404 error, give it more time. GitHub's deployment can take up to 5 minutes sometimes.

Adding More Pages

Create additional HTML files for more pages:

Link them together in your navigation:

<nav>
    <a href="index.html">Home</a>
    <a href="about.html">About</a>
    <a href="projects.html">Projects</a>
</nav>

Customizing With CSS

Plain HTML is ugly. Add a stylesheet.

  1. Create a file named style.css
  2. Add your CSS rules:
body {
    font-family: Arial, sans-serif;
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
    background-color: #f5f5f5;
}

h1 {
    color: #333;
}

nav a {
    margin-right: 15px;
    text-decoration: none;
    color: #0066cc;
}
  1. Link it in your HTML by adding this to your <head>:
<link rel="stylesheet" href="style.css">

Using a Custom Domain

Want your site at yourdomain.com instead of github.io? You can do this.

Step 1: Configure DNS

Go to your domain registrar (where you bought your domain) and add these DNS records:

Step 2: Configure GitHub

  1. In your repository Settings → Pages
  2. Under "Custom domain", type your domain (e.g., yourdomain.com)
  3. Check Enforce HTTPS
  4. Save and wait for the SSL certificate to provision (usually 5-30 minutes)

Your site now loads at your custom domain. DNS propagation can take up to 48 hours, but usually happens within a few hours.

GitHub Pages vs. Alternatives

Here's how GitHub Pages stacks up against other free hosting options:

Feature GitHub Pages Netlify Vercel
Cost Free Free tier Free tier
Custom domain ✅ Yes ✅ Yes ✅ Yes
Free SSL ✅ Yes ✅ Yes ✅ Yes
Server-side code ❌ No ❌ No ⚠️ Limited
Build tools ⚠️ Jekyll only ✅ All ✅ All
E-commerce ❌ No ⚠️ With plugins ⚠️ With plugins

GitHub Pages works fine for static sites. If you need server-side logic or build tools beyond Jekyll, look at Netlify or Vercel instead.

Common Problems and Fixes

404 Error After Deployment

Your default branch might not be "main". In Settings → Pages, verify the branch matches your actual branch name. Some repos use "master" instead.

Changes Not Showing Up

Clear your browser cache. GitHub Pages deployment takes 1-10 minutes. If it's been over 15 minutes, check your commit history to confirm your changes actually saved.

Repository Name Typo

If you named your repo incorrectly, rename it under Settings → Repository name. The URL must match your username exactly.

Images Not Loading

Check your file paths. If your image is at images/photo.jpg, reference it as <img src="images/photo.jpg">. Case sensitivity matters on GitHub.

Quick Reference

Is This Worth It?

For simple static sites, yes. The setup takes 15 minutes, costs nothing, and performs well enough for most use cases. The version control integration alone makes it worth it over traditional file-based hosting.

Don't expect to run a web app on this. GitHub Pages serves static files only. No PHP, no databases, no server-side processing. Know what you're getting into before you start.