Skip to main content

​
Overview

GitHub Pages is a free static site hosting service that deploys directly from a GitHub repository. It’s perfect if you’re already using GitHub for version control.
GitHub Pages is completely free for public repositories with unlimited bandwidth.

​
Prerequisites

  • A GitHub account (create one at github.com)
  • Your portfolio template folder ready to upload
  • Basic familiarity with GitHub (helpful but not required)

​
Deployment Steps

1

Create a GitHub Repository

  1. Log in to GitHub
  2. Click the + icon in the top-right corner
  3. Select New repository
  4. Name your repository (e.g., my-portfolio)
  5. Choose Public visibility
  6. Do NOT initialize with README, .gitignore, or license
  7. Click Create repository
For a personal portfolio at username.github.io, name your repository exactly username.github.io (replace username with your GitHub username).
2

Upload Your Portfolio Files

You have two options:

​
Option A: Upload via Web Interface (Easiest)

  1. On your repository page, click uploading an existing file
  2. Drag and drop your entire portfolio folder into the upload area
  3. Wait for all files to upload
  4. Scroll down and click Commit changes

​
Option B: Upload via Git Command Line

# Navigate to your portfolio folder
cd /path/to/your/portfolio

# Initialize git repository
git init

# Add all files
git add .

# Commit files
git commit -m "Initial portfolio commit"

# Add remote repository
git remote add origin https://github.com/username/repository-name.git

# Push to GitHub
git branch -M main
git push -u origin main
Make sure your main HTML file is named index.html at the root level.
3

Enable GitHub Pages

  1. In your repository, click Settings (top navigation)
  2. Scroll down and click Pages in the left sidebar
  3. Under Source, select Deploy from a branch
  4. Under Branch, select main (or master) and folder / (root)
  5. Click Save
GitHub will begin deploying your site. This takes 1-2 minutes.
You’ll see a message: “Your site is ready to be published at https://username.github.io/repository-name/”
4

Access Your Live Portfolio

  1. Wait for the deployment to complete (refresh the Pages settings page)
  2. Once ready, you’ll see: “Your site is live at https://...”
  3. Click the URL to view your live portfolio
  4. Share this URL with anyone to showcase your work
Bookmark your GitHub Pages URL or add it to your repository description for easy access.

​
Updating Your Portfolio

To make changes after deployment:
1

Edit Your Local Files

Make changes to your HTML, CSS, or JavaScript files locally.
2

Upload Changes

Via Web Interface:
  • Navigate to the file in your repository
  • Click the pencil icon (Edit)
  • Make changes and commit
Via Git:
git add .
git commit -m "Update portfolio content"
git push
3

Wait for Redeployment

GitHub Pages automatically redeploys when you push changes. Wait 1-2 minutes, then refresh your live site.

​
Custom Domain Setup (Optional)

1

Purchase a Domain

Buy a domain from a registrar like:
  • Namecheap
  • Google Domains
  • GoDaddy
  • Cloudflare
2

Configure DNS Records

In your domain registrar’s DNS settings, add these records:For apex domain (example.com):
Type: A
Name: @
Value: 185.199.108.153

Type: A
Name: @
Value: 185.199.109.153

Type: A
Name: @
Value: 185.199.110.153

Type: A
Name: @
Value: 185.199.111.153
For subdomain (www.example.com):
Type: CNAME
Name: www
Value: username.github.io
3

Configure GitHub Pages

  1. Go to repository Settings > Pages
  2. Under Custom domain, enter your domain (e.g., www.example.com)
  3. Click Save
  4. Wait for DNS check to complete
  5. Enable Enforce HTTPS (recommended)
4

Wait for Propagation

DNS changes can take 24-48 hours to propagate. Your site will be accessible at your custom domain once complete.
Keep the CNAME file in your repository. GitHub Pages creates this automatically when you set a custom domain.

​
Troubleshooting

​
Site Not Loading

Ensure index.html is at the root level of your repository, not in a subfolder.
Go to Settings > Pages and confirm the source branch is set correctly.
Look at the Actions tab in your repository for deployment logs.

​
CSS/Images Not Loading

Change absolute paths like /css/style.css to relative paths like css/style.css or ./css/style.css.
Ensure file names match exactly (case-sensitive on GitHub Pages).

​
Best Practices

Version Control Benefits: Using GitHub for deployment also gives you version control, allowing you to track changes and revert if needed.
GitHub Actions: For advanced users, you can automate deployments using GitHub Actions workflows.
GitHub Pages has a soft bandwidth limit of 100GB/month and 10 builds/hour. This is more than sufficient for personal portfolios.

​
Next Steps

Custom Domain

Follow the custom domain setup guide above to use your own domain name.

SEO Optimization

Add meta tags and optimize your portfolio for search engines.

Build docs developers (and LLMs) love

Get started for freeTalk to us