How to Set Up username.github.io- Complete Setup Guide

What Is username.github.io and Why You Need It

Your username.github.io site is free web hosting provided by GitHub. It lets you publish a website directly from a repository. No paid hosting. No complex setup. Just you, Git, and a live URL.

This works for:

You get HTTPS by default. Your site loads fast. And it costs exactly nothing.

Prerequisites Before You Start

You need two things ready:

That's it. No credit card. No technical degree required.

Checking Your Username

Your GitHub username determines your site URL. If your username is johnsmith, your site will be johnsmith.github.io.

Usernames with special characters or hyphens work too, but keep it simple. Spaces cause problems.

Setting Up Your Repository

Your website lives in a specific repository. GitHub looks for it by name.

Step 1: Create the Repository

  1. Log into GitHub
  2. Click the + button in the top right corner
  3. Select "New repository"
  4. Name it exactly: username.github.io
  5. Set it to Public
  6. Click "Create repository"

The name must match your username exactly, including capitalization. If you get this wrong, nothing works.

Step 2: Add Your Content

You have two options here. Pick the one that matches your comfort level.

Option A: Upload Files Directly

Good for beginners or quick updates.

  1. On your repository page, click "Add file" → "Create new file"
  2. Name it index.html
  3. Paste your HTML code
  4. Click "Commit changes"

Option B: Clone and Use Git

Better for ongoing development and version control.

  1. Click the "Code" button on your repository
  2. Copy the HTTPS URL
  3. Run git clone [your-url] in your terminal
  4. Add your files to the cloned folder
  5. Run git add .
  6. Run git commit -m "Initial commit"
  7. Run git push origin main

Your First index.html File

GitHub Pages looks for index.html by default. Here's the bare minimum you need:

<!DOCTYPE html>
<html>
<head>
    <title>My Site</title>
</head>
<body>
    <h1>Hello, World</h1>
    <p>This is my website.</p>
</body>
</html>

Save this as index.html and push it to your repository.

Enabling GitHub Pages

New repositories sometimes have GitHub Pages disabled by default. Turn it on:

  1. Go to your repository settings
  2. Scroll down to "GitHub Pages" section
  3. Under "Source", select "Deploy from a branch"
  4. Select your branch (usually main)
  5. Select the / (root) folder
  6. Click "Save"

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

Custom Domains vs Default URL

You get a free subdomain, but maybe you want your own domain instead.

Feature Default URL Custom Domain
Cost Free Domain purchase required
Setup time Minutes 30-60 minutes
SSL certificate Automatic Automatic via GitHub
Maintenance None DNS configuration

For most people, the default URL works fine. Custom domains make sense only if you need branding or already own a domain.

Adding a Custom Domain

  1. In repository Settings → GitHub Pages
  2. Enter your domain under "Custom domain"
  3. Click "Save"
  4. Add DNS records at your domain registrar:
    • A records pointing to GitHub's IP addresses
    • CNAME record pointing to username.github.io
  5. Wait up to 24 hours for DNS propagation

Jekyll: The Built-in Static Site Generator

GitHub Pages uses Jekyll automatically. Jekyll transforms Markdown files into HTML. You don't have to use it, but it's there if you want cleaner content management.

Why Use Jekyll?

Getting Started with Jekyll

Create a file named _config.yml in your repository root:

title: My Site
description: What this site is about
theme: minima

Create a folder named _posts. Inside it, add files named like 2024-01-15-my-post.md. Jekyll processes these automatically.

Common Problems and Fixes

404 Error After Publishing

Your index.html might be in the wrong folder. It must be in the repository root, not in a subfolder. Check your branch settings too—make sure you're deploying from main.

Site Not Updating

GitHub caches aggressively. After pushing changes, wait 2-5 minutes. Hard refresh with Ctrl+Shift+R. If still broken, check your repository's Actions tab for deployment errors.

Branch Not Showing

GitHub Pages only deploys from main, gh-pages, or master. If your branch has a different name, rename it or change the source in settings.

Custom Domain SSL Not Working

Enable "Enforce HTTPS" in your GitHub Pages settings. If it stays grayed out, wait 24 hours after configuring DNS. The certificate takes time to provision.

Project Pages vs User Pages

There are two types of GitHub Pages sites:

Type URL Format Use Case
User Pages username.github.io Personal presence, portfolio, resume
Project Pages username.github.io/project-name Documentation, demos, specific projects

User pages come from the username/username.github.io repository. Project pages come from any repository's gh-pages branch or a docs folder.

Making Updates

The workflow never changes:

  1. Edit or add files locally
  2. Commit your changes
  3. Push to GitHub
  4. Wait 1-2 minutes
  5. Check your live site

Each push triggers a rebuild. GitHub handles everything from there.

What You Cannot Do

GitHub Pages has limits:

This isn't WordPress hosting. It's static HTML, CSS, and JavaScript. If you need dynamic features, you'll use client-side JavaScript or connect to external APIs.

Quick Reference

That's the complete setup. Create the repo, push an HTML file, enable Pages, wait two minutes. It works.