Creating a GitHub Pages Website

A Step-by-Step Guide to Hosting Static Websites for Free

What is GitHub Pages? Prerequisites Step-by-Step Guide Custom Domain Troubleshooting Resources

What is GitHub Pages?

GitHub Pages is a free static site hosting service provided by GitHub that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally runs them through a build process, and publishes a website.

Key Features

  • Free hosting for static websites
  • Custom domain support (optional)
  • SSL encryption (HTTPS) by default
  • Git integration for version control
  • Jekyll support for static site generation
  • Unlimited bandwidth and traffic
Types of GitHub Pages

There are three main types:

  • User/Organization Pages: username.github.io
  • Project Pages: username.github.io/repository
  • Custom Domain: Your own domain name
Limitations

What GitHub Pages can't do:

  • Server-side code (PHP, Ruby, Python)
  • Dynamic database-driven sites
  • Server-side authentication
  • Heavy processing on server
  • More than 1GB bandwidth/month (rarely hit)
Perfect For

GitHub Pages is ideal for:

  • Personal portfolios
  • Project documentation
  • Blogs (with Jekyll)
  • Educational resources
  • Resume websites
  • Small business sites

Prerequisites

Before you start, make sure you have these basics covered:

GitHub Account

You need a free GitHub account:

  1. Go to github.com
  2. Click "Sign up"
  3. Choose a username (this will be part of your URL)
  4. Verify your email address

Your username becomes part of your GitHub Pages URL: username.github.io

Basic Knowledge

You should understand:

  • Basic HTML and CSS
  • How to create and edit text files
  • Basic Git concepts (optional but helpful)
  • File organization

Don't worry if you're new to Git - we'll cover the basics!

Tools

Helpful tools to have:

  • A code editor (VS Code, Sublime Text, etc.)
  • Git installed on your computer (optional)
  • A modern web browser
  • File Explorer/Finder knowledge

You can do everything through the GitHub website if needed!

Step-by-Step Guide

Follow these steps to create your first GitHub Pages site:

  1. Create a New Repository

    On GitHub, create a new repository with this specific name:

    username.github.io

    Replace "username" with your actual GitHub username. This naming convention is important!

    Important: The repository must be public for the free version of GitHub Pages.

  2. Initialize with README

    When creating the repository:

    • Check "Add a README file"
    • Choose a license if you want (optional)
    • Click "Create repository"

    The README file is your project's front page on GitHub.

  3. Add Your First HTML File

    Create a file named index.html in your repository:

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My GitHub Pages Site</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
            line-height: 1.6;
        }
        h1 {
            color: #0366d6;
        }
    </style>
</head>
<body>
    <h1>Hello World!</h1>
    <p>My GitHub Pages site is live!</p>
    <p>Visit: <code>https://username.github.io</code></p>
</body>
</html>

    You can add this file directly on GitHub by clicking "Add file" → "Create new file".

  4. Enable GitHub Pages

    Go to your repository Settings → Pages:

    • Under "Source", select "Deploy from a branch"
    • Choose "main" branch (or "master" if you have that)
    • Select the / (root) folder
    • Click "Save"
    It may take 1-2 minutes for your site to deploy. You'll see a "Your site is published at..." message when it's ready.

  5. Visit Your Site

    Open a new tab and go to:

    https://username.github.io

    Replace "username" with your GitHub username. You should see your "Hello World!" page!

    Pro Tip: You can simply type username.github.io without the https:// in your browser's address bar. Modern browsers will automatically use HTTPS, and GitHub will load your site securely. This is a great shorter way to access your site!

    The URL is always https:// - GitHub provides SSL certificates automatically.

  6. Customize Your Site

    Add more files to your repository:

    • style.css - for styling
    • script.js - for interactivity
    • about.html - additional pages
    • images/ folder - for images

    Link to CSS files in your HTML:

    <link rel="stylesheet" href="style.css">

  7. Add Simple JavaScript (Beginner Example)

    Create a file named script.js with this basic code:

    // This code adds interactivity to your website

// Wait for the page to load
document.addEventListener('DOMContentLoaded', function() {

    // Get the button and message elements
    const button = document.getElementById('demoButton');
    const message = document.getElementById('demoMessage');

    // Add a click event to the button
    button.addEventListener('click', function() {
        // Change the text and color when clicked
        message.textContent = 'Button clicked! JavaScript is working!';
        message.style.color = '#28a745';

        // Add a simple animation
        button.style.transform = 'scale(0.95)';
        setTimeout(() => {
            button.style.transform = 'scale(1)';
        }, 150);
    });

    // Simple console log to show it's working
    console.log('GitHub Pages JavaScript loaded successfully!');
});

    Update your index.html to include the JavaScript:

    <!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My GitHub Pages Site</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>Hello World!</h1>
    <p id="demoMessage">Click the button to test JavaScript.</p>
    <button id="demoButton">Click Me!</button>
    <script src="script.js"></script>
</body>
</html>

    This simple example shows how to add interactivity to your GitHub Pages site.

Quick Test: Is Your Site Live?

Copy and paste this command in your terminal (or use a web browser):

curl -I https://username.github.io

You should see HTTP/2 200 which means your site is successfully deployed!

Using a Custom Domain

You can use your own domain name (like yourdomain.com) with GitHub Pages:

Step 1: Buy a Domain

Purchase a domain from:

  • Namecheap
  • GoDaddy
  • Google Domains
  • Cloudflare

Prices range from $10-15/year for a .com domain.

Step 2: Add CNAME File

In your repository, create a file named CNAME (all caps) with one line:

yourdomain.com

Or if you want www:

www.yourdomain.com

Commit this file to your repository.

Step 3: Configure DNS

In your domain registrar's DNS settings, add:

  • A records pointing to: 
    185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
  • Or a CNAME record pointing to: 
    username.github.io
Note: DNS changes can take up to 48 hours to propagate globally. GitHub will automatically provision an SSL certificate for your custom domain.

Verify HTTPS on Custom Domain

After setting up your custom domain, GitHub will automatically enable HTTPS. Check:

  1. Wait a few minutes after DNS propagation
  2. Visit https://yourdomain.com
  3. Look for the padlock icon in your browser's address bar
  4. If it doesn't work immediately, wait up to 24 hours for SSL provisioning

Common Issues & Troubleshooting

404 Error

Problem: "Page not found" when visiting your site.

Solutions:

  • Make sure repository is named correctly: username.github.io
  • Check that GitHub Pages is enabled in Settings → Pages
  • Ensure you have an index.html file
  • Wait 1-2 minutes after enabling Pages
CSS/JS Not Loading

Problem: Styles or scripts aren't working.

Solutions:

  • Check file paths are correct (case-sensitive!)
  • Use relative paths: href="css/style.css"
  • Clear browser cache (Ctrl+F5 or Cmd+Shift+R)
  • Check browser console for errors (F12)
Updates Not Showing

Problem: Changes aren't visible on live site.

Solutions:

  • GitHub Pages builds take 1-2 minutes
  • Check Actions tab for build status
  • Clear browser cache
  • Try incognito/private browsing mode

Quick Debugging Commands

Use these commands to check your site's status:

# Check if site is accessible
curl -I https://username.github.io

# Check DNS for custom domain
nslookup yourdomain.com

# Check SSL certificate
openssl s_client -connect yourdomain.com:443
Build Failures: If your site fails to build, check the Actions tab in your repository for error messages. Common issues include Jekyll build errors or syntax errors in configuration files.

Resources & Further Learning

Official Documentation
Learning Resources
Example Sites

Next Steps

Once you have a basic site, consider:

Advanced Features
  • Using Jekyll for blogging
  • Adding Google Analytics
  • Implementing a contact form (with Formspree or similar)
  • Adding a custom 404 page
Development Tips
  • Use Git locally for version control
  • Set up a local development server
  • Learn about responsive design
  • Explore GitHub Actions for CI/CD
Create Your GitHub Pages Site Now