GitHub Pages

GitHub Pages is a static site hosting service that publishes websites directly from a Git repository. It’s a reliable, low-friction option for hosting personal profiles, project documentation, or organization landing pages without managing servers.

The image is a screenshot of the GitHub Pages settings interface, highlighting the steps to access and configure GitHub Pages for hosting static websites from a repository.

What can GitHub Pages host?

Static web assets: HTML, CSS, JavaScript, images, fonts, and other static files.
Sites built by static site generators (SSGs): GitHub Pages will automatically build Jekyll sites. For other SSGs (Hugo, Gatsby, Eleventy, etc.), include a build step (locally or via CI) and publish the generated output to the Pages branch/folder.

How GitHub Pages works

Deployment source: In your repository Settings → Pages you choose a branch and an optional folder (for example gh-pages, or main with /docs) as the publishing source.
Automatic publishing: Changes pushed to the chosen branch/folder trigger GitHub Pages to publish the latest static content. For Jekyll sites, GitHub can build automatically.
Optional build pipelines: Use GitHub Actions to run custom builds (compile SSG sources, bundle assets, run tests) and publish the generated static files to the Pages branch/folder.
Public accessibility: Sites published on GitHub Pages are publicly reachable by default and served over HTTPS.

Default and custom domains By default, Pages sites use the github.io domain, for example:

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

You can configure a custom domain in the repository Settings → Pages. To enable a custom domain:

Add your domain in the Pages settings.
Create a CNAME file in the published site (root of the branch/folder) containing your custom domain, or use the Pages UI.
Update DNS records (usually an A record or ALIAS/ANAME for apex domains, and a CNAME for subdomains). GitHub will provision HTTPS for enabled custom domains.

GitHub Pages serves only static content — server-side runtimes like Node.js, Python, or PHP are not supported. For dynamic behavior use client-side JavaScript calling APIs, or pair Pages with serverless/backend services.

Common usage patterns

Use case	Description	Example
Personal site	Portfolio, blog, or CV hosted under your user namespace	`https://your-username.github.io`
Project site	Documentation, demos, or landing pages for a repository	`https://your-username.github.io/your-repo`
Organization site	Centralized docs, marketing, or product pages for a GitHub organization	Use a repo named `org-name.github.io`

Quick setup (step-by-step)

Create or choose a repository.
Prepare your static site files (or your SSG source).
Configure Pages source: Settings → Pages → select branch and folder (/ or /docs).
If using a non-Jekyll SSG, add a CI workflow to build and publish the generated output.

Example: simple GitHub Actions workflow to build and deploy static output

This example runs a build and deploys the generated public (or dist) folder to the gh-pages branch using peaceiris/actions-gh-pages. The YAML is shown as a reference — customize build steps for your site generator.

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          npm install
      - name: Build site
        run: |
          npm run build   # outputs to 'public' or 'dist'
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

When to avoid GitHub Pages

Do not use GitHub Pages when your site requires server-side code execution, WebSocket connections, or other server runtimes. For dynamic backends, choose a platform that supports server-side processes or use serverless APIs alongside Pages.

Additional tips

Use the docs folder on main if you prefer to keep pages in the same branch as source code.
For Jekyll users, GitHub Pages supports a subset of plugins — use Actions to run a full Jekyll build if you rely on unsupported plugins.
Monitor the Pages build logs (Settings → Pages) when troubleshooting build or publish failures.
For private repositories, Pages can be configured to publish publicly or be limited to internal/organization members depending on your account and settings.

References and further reading

This overview covered what GitHub Pages hosts, how publishing works, common configuration choices, a sample CI workflow, and practical tips for deployment and domains.

Watch Video

Demo Describe How to Create Edit and Delete Wiki Pages

Demo Describe GitHub Pages

Introduction

Git and GitHub Basics

GitHub Entities

GitHub Markdown

GitHub Desktop

GitHub Mobile

GitHub Repositories

Issues

Pull Requests

Discussions

Notifications

Gists, Wikis, and GitHub Pages

GitHub Actions

GitHub Copilot

GitHub Codespaces

Manage Your Work with GitHub Projects

Authentication and Security

GitHub Administration

Benefits of Open-Source Community

Benefits of Open Source – Applications

Watch Video