GitHub Pages: Deploy Sites Directly from Your Repository

In this tutorial, you'll learn about GitHub Pages: Deploy Sites Directly from Your Repository. We cover key concepts, practical examples, and best practices.

GitHub Pages is a free static site hosting service that takes HTML, CSS, and JavaScript from a repository and publishes them as a live website automatically.

In this tutorial, you'll learn how to deploy websites directly from your GitHub repository using GitHub Pages. GitHub Pages hosts static sites for free, directly from your repo — perfect for documentation, portfolios, and project pages. By the end, you'll configure builds, set up custom domains, and deploy both project and user pages.

flowchart TD
  A[Create repository] --> B{Pages type?}
  B --> C[User/Org: username.github.io]
  B --> D[Project: username.github.io/repo]
  C --> E[Branch: main, folder: root]
  D --> F[Branch: gh-pages or /docs]
  E --> G[Enable Pages in Settings]
  F --> G
  G --> H[Site is live!]
  H --> I[Add custom domain]
  I --> J[Configure DNS + CNAME]

Types of GitHub Pages

Setting Up a User Site

Create a repository named <your-username>.github.io:

git init
echo "# My Portfolio" > index.html
git add index.html
git commit -m "Initial commit"
git remote add origin https://github.com/your-username/your-username.github.io.git
git push -u origin main

Enable Pages in repository Settings > Pages > Deploy from main branch > root folder. Your site is live at https://your-username.github.io.

Setting Up a Project Site

For a project site (e.g., documentation), use the gh-pages branch:

# Create and switch to gh-pages branch
git checkout --orphan gh-pages
git rm -rf .
echo "<h1>Project Docs</h1>" > index.html
git add index.html
git commit -m "Initial project pages"
git push -u origin gh-pages

In Settings > Pages, set branch to gh-pages and folder to /root.

Using Jekyll

Enable Jekyll for automatic Markdown-to-HTML conversion:

# _config.yml at repository root
title: My Project Site
description: Documentation for my awesome project
theme: jekyll-theme-cayman

Create a Jekyll page:

---
title: Getting Started
---
## Welcome

This page is written in Markdown and automatically converted to HTML.

Custom Domain

Add a custom domain:

1. In repo Settings > Pages, enter your domain (e.g., docs.example.com)
2. Create a CNAME file (optional, GitHub creates it):

docs.example.com

3. Configure DNS at your provider:

Jekyll Themes

GitHub Pages supports several Jekyll themes:

Set a theme in _config.yml:

theme: jekyll-theme-cayman
title: My Project
description: Short description for search engines
show_downloads: true
google_analytics: UA-XXXXX-Y

Build Configuration

Use GitHub Actions for custom build steps:

# .github/workflows/pages.yml
name: Deploy to Pages
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build site
        run: |
          npm install
          npm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v2

Common Errors

Practice Questions

Challenge

Create a personal portfolio site using GitHub Pages with a custom domain. Use Jekyll with the Cayman theme. Create at least three pages: index (about you), projects (with pinned repos), and contact. Set up a GitHub Actions workflow that builds the site on push. Add a custom domain with HTTPS enabled.

Real-World Task

You need to publish documentation for an open-source library. Create a /docs folder in the repository with Markdown files for installation, usage, API reference, and contributing guidelines. Configure GitHub Pages to serve from the /docs folder on the main branch. Add a _config.yml with a Jekyll theme. Set up a custom subdomain (docs.projectname.com). This documentation setup is used by DodaTech for all open-source projects including DodaZIP.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.