How to Publish a Website with GitHub Pages: A Step-by-Step Guide

In today’s digital world, having a web presence is essential—whether you’re showcasing a portfolio, maintaining project documentation, or sharing your blog. Fortunately, GitHub Pages offers a fast, free, and reliable way to publish websites directly from your GitHub repositories.

In this blog post, we’ll walk you through everything you need to know to get started with GitHub Pages, from setup to deployment.

📌 What is GitHub Pages?

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a GitHub repository and publishes them as a website. It’s ideal for personal, project, or organization sites, and it’s tightly integrated with Git and GitHub workflows.

✅ Prerequisites

Before you begin, make sure you have:

  • A GitHub account
  • Git installed on your local machine (optional, but recommended)
  • A basic understanding of HTML or a static site generator (e.g., Jekyll)

🚀 Step 1: Create a New GitHub Repository

  1. Go to github.com and log in.
  2. Click the + icon in the top-right corner and select New repository.
  3. Name your repository. If you want a user or organization site, name it username.github.io (replace username with your GitHub handle).
  4. Add a README if you wish, and click Create repository.

🧱 Step 2: Add Your Website Files

You can add your website’s files in one of two ways:

Option A: Upload Files via GitHub UI

  1. Click Add file > Upload files.
  2. Drag and drop your HTML, CSS, JS, and image files.
  3. Click Commit changes.

Option B: Push from Local Repository Using Git

# Clone the repo
git clone https://github.com/username/repository-name.git
cd repository-name

# Add your files
cp -r /path/to/your/site/* .

# Stage, commit, and push
git add .
git commit -m "Add website files"
git push origin main

🌐 Step 3: Enable GitHub Pages

  1. Navigate to your repository on GitHub.
  2. Click Settings > Pages in the sidebar.
  3. Under Source, select the branch (e.g., main) and folder (/root or /docs) where your site files are located.
  4. Click Save.

GitHub will generate a link to your live site, such as:

https://username.github.io/repository-name/

For user or organization sites, it will be:

https://username.github.io/

🛠 Optional: Use a Static Site Generator like Jekyll

If you’re building a blog or documentation site, consider using Jekyll, which integrates seamlessly with GitHub Pages. Simply include a _config.yml file and structure your content using Markdown files.

GitHub Pages even builds your Jekyll site for you automatically!

🧪 Step 4: Test Your Website

Open your published site’s URL in a browser to ensure everything looks good. Check:

  • Page load speed
  • Broken links
  • Mobile responsiveness
  • Correct formatting and images

📤 Updating Your Site

To update your site:

  1. Make changes locally or on GitHub.
  2. Commit and push the changes.
  3. GitHub Pages will automatically redeploy your site.

🔒 Custom Domains and HTTPS

Want to use your own domain?

  1. Add your domain name in Settings > Pages.
  2. Create a CNAME file in your repository with your domain name.
  3. Update your DNS records to point to GitHub Pages.

GitHub also supports free HTTPS for custom domains!

🧩 Troubleshooting Tips

  • 404 Error: Make sure index.html is in the root directory or the correct folder (/docs).
  • Styling not applied: Check that CSS file paths are correct and relative.
  • Jekyll issues: Add a .nojekyll file to the root if you’re not using Jekyll but encounter build issues.

🎉 Conclusion

GitHub Pages makes it incredibly easy to publish and maintain static websites, especially for developers already using GitHub for version control. With just a few clicks and commits, you can have your personal or project site live on the web.

Whether you’re a beginner or an experienced developer, GitHub Pages is a powerful tool to keep in your web development toolkit.

Sharing Is Caring:

Leave a Comment