GitHub Pages Basics
GitHub Pages is a free static website hosting service that takes files from your repository and publishes them to the web. Perfect for personal websites, project documentation, portfolios, and open source project pages.
GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files from a GitHub repository and publishes them to a website. It's completely free, with no server setup required, and integrates seamlessly with your Git workflow. Every time you push changes to your repository, GitHub Pages automatically rebuilds and deploys your site.
There are three types of GitHub Pages sites. A user site is associated with your GitHub username and serves from a repository named username.github.io. An organization site works similarly for GitHub organizations. A project site is attached to any repository and served from a subdirectory like username.github.io/repository-name/. Each type has slightly different default URLs, but all share the same underlying functionality.
Enabling GitHub Pages takes less than a minute. Navigate to your repository on GitHub, click the "Settings" tab, then scroll down to the "Pages" section on the left sidebar. In the "Build and deployment" section, you'll choose the source branch and folder for your site.
For a project site, you typically select the main branch and the /(root) folder, or the docs folder if your site files are in a docs directory. For a user or organization site, you need a repository named username.github.io, and you'll select the main branch as the source. After saving, GitHub will provide you with a URL where your site is published—usually https://username.github.io/repository-name/.
# Your site will be available at:
https://username.github.io/repository-name/
# For user sites (username.github.io repository):
https://username.github.io/
GitHub Pages gives you flexibility in how you organize your site files. You can place your site content directly in the root of your repository—just create an index.html file, and it becomes your homepage. This is the simplest approach for small sites or single-page applications.
Alternatively, you can use the docs/ folder. This is useful when your repository contains both source code and documentation. By pointing Pages to the docs/ folder, you keep your site files separate from your application code. This is a common pattern for open source projects that want their documentation site alongside the source code.
For Jekyll sites (which we'll cover later), you'll typically keep your source files in the root and let Jekyll build the site. GitHub Pages automatically detects Jekyll configuration files and builds the site using Jekyll when you push.
# Root structure (simplest)
my-repo/
├── index.html
├── about.html
├── style.css
└── script.js
# Docs folder structure
my-repo/
├── src/ # source code
├── docs/ # site files
│ ├── index.html
│ └── style.css
└── README.md
GitHub Pages has built-in support for Jekyll, a static site generator. When you push files with a _config.yml file, GitHub automatically runs Jekyll to build your site. This is incredibly powerful—you can write your content in Markdown, and Jekyll converts it to HTML, applies a theme, and generates a complete website.
GitHub Pages comes with several official themes that you can apply with a single line in your _config.yml file. Themes like "Minima", "Cayman", "Leap Day", and "Hacker" provide professional-looking designs without any CSS work. To use a theme, simply set theme: minima (or your chosen theme) in the configuration file.
# _config.yml - Basic Jekyll configuration
title: My Awesome Site
description: A site about awesome things
theme: minima
# You can also use remote themes (GitHub-hosted themes)
remote_theme: pages-themes/cayman
If you want more control, you can create your own custom Jekyll theme by adding layouts and includes to your repository. Or you can use a remote theme—a theme hosted on GitHub that you reference by repository name. This keeps your repository clean while still using a sophisticated design.
While GitHub Pages gives you a username.github.io/repo URL, you can use your own domain name. This is essential for professional portfolios, company websites, or any project that needs a custom brand identity. Setting up a custom domain involves two steps: configuring your domain's DNS and telling GitHub about your domain.
First, purchase a domain from a registrar like Namecheap, GoDaddy, or Google Domains. Then, in your domain's DNS settings, create an A record pointing to GitHub's IP addresses (185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153) or a CNAME record pointing to username.github.io. For user sites, use A records; for project sites, use a CNAME record.
Second, in your repository's Pages settings, enter your custom domain in the "Custom domain" field. GitHub will create a CNAME file in your repository with your domain name. That file is essential—it tells GitHub to respond to requests for your domain. Once DNS propagates (which can take minutes to hours), your site will be available at your custom domain.
# DNS Configuration (example for project site)
Type: CNAME
Name: www (or @ for apex domain)
Value: username.github.io
# Also create a file in your repository: CNAME
www.myawesomesite.com
Creating your first GitHub Pages site is incredibly simple. Let's walk through a basic example. Create a new repository on GitHub (or use an existing one). Add an index.html file with the following content:
<!DOCTYPE html>
<html>
<head>
<title>My GitHub Pages Site</title>
</head>
<body>
<h1>Hello from GitHub Pages!</h1>
<p>This is my first static site hosted for free.</p>
</body>
</html>
Commit this file to your repository. Then go to Settings → Pages and select the source branch (main) and folder (root). After saving, wait a minute, then visit the URL shown. You'll see your custom HTML page live on the internet! Every time you push changes, the site updates automatically.
For modern static site generators like React, Vue, or Hugo, you'll want to build your site before publishing. GitHub Actions can automate this process. You can set up a workflow that builds your site (running npm run build, for example) and then deploys the output to the gh-pages branch.
This approach is powerful because you can use any static site generator—not just Jekyll. You keep your source code in main, and the built site in the gh-pages branch. When you push to main, GitHub Actions builds the site and automatically updates the live site.
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run build
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build
username.github.io domains, SSL is automatically enabled. For custom domains, GitHub provides Let's Encrypt certificates automatically. No configuration needed._posts folder with markdown files named YYYY-MM-DD-title.md. Jekyll automatically generates blog posts with dates, categories, and permalinks. Many Jekyll themes include blog layouts built in.bundle exec jekyll serve if you have Ruby installed. For other static site generators, they usually have built-in development servers. GitHub Actions also lets you preview builds before merging.username.github.io. You need a repository named exactly username.github.io. A project site is attached to any repository and served from username.github.io/repository-name. User sites are great for personal portfolios; project sites are perfect for documentation and project landing pages.GitHub Pages turns your repository into a website. Start with a simple index.html, then explore themes, custom domains, and static site generators to build something amazing.