What is GitHub Pages?
GitHub Pages is a free static site hosting service provided by GitHub. It takes HTML, CSS, and JavaScript files directly from a repository, optionally runs them through a build process (like Jekyll), and publishes the result as a live website - complete with HTTPS.
Key Features
- Free hosting for static websites
- Custom domain support (optional)
- SSL/HTTPS encryption enabled by default
- Deep Git integration for version control
- Jekyll support built into the platform
- Unlimited bandwidth for reasonably-sized sites
- GitHub Actions for custom build pipelines
- User / Organization site -
username.github.io - Project site -
username.github.io/repository - Custom domain - your own domain name
GitHub Pages cannot run:
- Server-side languages (PHP, Ruby, Python, Node)
- Databases or dynamic server logic
- Server-side authentication
- Heavy background processing
- Sites larger than 1 GB (soft limit)
- More than 100 GB bandwidth/month (soft limit)
- Personal portfolios
- Project documentation
- Blogs (with Jekyll)
- Resume websites
- Educational resources
- Product landing pages
- Small business sites
Prerequisites
Before you start, make sure you have the following covered:
- Go to github.com
- Click Sign up
- Choose a username (this becomes part of your URL)
- Verify your email address
Your username becomes part of your GitHub Pages URL:
username.github.io
- Basic HTML and CSS (JavaScript is helpful but not required)
- Creating and editing text files
- Basic Git concepts (helpful but optional)
- File organisation & folder structure
New to Git? Don't worry - we cover everything you need.
- A code editor (VS Code recommended)
- Git installed (required for Path B)
- A modern browser
- Ruby + Bundler (for Path B only)
On Windows, install Git for Windows - it ships with Git Bash, which runs the Linux-style commands in this guide verbatim.
macOS and Linux already have a usable terminal, so nothing extra is required.
Choose Your Path
There are two ways to build a GitHub Pages site, and you can mix them:
Simple Static Site
Plain HTML, CSS and JavaScript committed directly. Fastest to set up, no build step, no local tooling required.
- Perfect for landing pages and small sites
- No Ruby or Node needed
- Live in under 5 minutes
Jekyll-Powered Site
Use Jekyll to build a site from templates, data files, and Markdown. GitHub builds it for you on every push.
- Blogs, docs sites, portfolios
- Reusable layouts & includes
- Data-driven pages from JSON/YAML
Path A - Simple Static Site
Follow these steps to have a live website in under five minutes.
-
Create a new repository
Create a public repository named exactly:
username.github.ioReplace
usernamewith your GitHub username. The naming convention is what tells GitHub to serve the repo as your root site.Important: On free accounts the repository must be public for Pages to work. -
Initialise with a README
- Tick Add a README file
- (Optional) Choose a licence
- Click Create repository
-
Add your first HTML file
Create a file named
index.htmlin the repository root:index.html<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>My GitHub Pages Site</title> <style> body { font-family: system-ui, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.6; color: #24292e; } h1 { color: #0366d6; } </style> </head> <body> <h1>Hello World!</h1> <p>My GitHub Pages site is live.</p> <p>Visit: <code>https://username.github.io</code></p> </body> </html>You can add it directly on GitHub: Add file → Create new file, paste the code, then commit.
-
Enable GitHub Pages
In your repository, go to Settings → Pages:
- Under Source, choose Deploy from a branch
- Select the main branch
- Select the
/ (root)folder - Click Save
Deployment takes 1-2 minutes. You'll see “Your site is live at…” when it's ready. -
Visit your site
Open a new tab and go to:
https://username.github.ioYou should see your Hello World page in all its glory.
Pro tip: Modern browsers will addhttps://for you - you can just typeusername.github.io. -
Customise it
Add more files to your repository:
style.css- external stylesheetscript.js- interactivityabout.html- extra pagesimages/- image assets
Link your CSS in HTML like so:
<link rel="stylesheet" href="style.css"> -
Add a splash of JavaScript
Create
script.js:script.jsdocument.addEventListener('DOMContentLoaded', () => { const button = document.getElementById('demoButton'); const message = document.getElementById('demoMessage'); button.addEventListener('click', () => { message.textContent = 'Button clicked! JavaScript is working.'; message.style.color = '#28a745'; button.style.transform = 'scale(0.95)'; setTimeout(() => { button.style.transform = 'scale(1)'; }, 150); }); });Then include it in your HTML just before
</body>:<p id="demoMessage">Click the button to test JavaScript.</p> <button id="demoButton">Click Me!</button> <script src="script.js"></script>
Quick sanity check
From a terminal, verify your site is live. Note that Windows PowerShell aliases
curl to Invoke-WebRequest,
so use curl.exe to get the real thing.
curl.exe -I https://username.github.io
curl -I https://username.github.io
Look for HTTP/2 200. If you see that, you're good to go.
Path B - Jekyll-Powered Site
Jekyll is a static site generator written in Ruby. It's built into GitHub Pages, so you don't even need to run a build step yourself - GitHub will build your site automatically when you push. The benefit is that you can use layouts, includes, data files, Markdown, and Liquid templating to avoid repeating yourself.
1. Install Jekyll locally
Jekyll needs Ruby. Follow the guide for your operating system:
- Install RubyInstaller for Windows (Ruby+Devkit 3.x)
- Run the installer and keep ridk install ticked
- In the popup, choose option 3 (MSYS2 + MINGW)
- Open a new terminal and run:
gem install jekyll bundler
If gem isn't recognised, your terminal was opened before
the installer finished. Close it, open a fresh one, and try again.
Use your system package manager, then install the gems:
# macOS (with Homebrew)
brew install ruby
gem install jekyll bundler
# Ubuntu / Debian
sudo apt install ruby-full build-essential
gem install jekyll bundler
On some distros gem install needs
sudo, or you can install into your home directory with
gem install --user-install.
Verify the install (this works the same on every platform):
jekyll -v
bundle -v
2. Create your project
Scaffold a new Jekyll site (or create the folders by hand):
jekyll new my-site --blank
cd my-site
The --blank flag gives you a bare scaffold - no theme, no
boilerplate - which is ideal if you want full control over the markup.
Here's a recommended structure. You don't need every folder - start with the ones you need:
my-site/ ├── _data/ # JSON / YAML / CSV files for templates │ └── navigation.yml ├── _includes/ # Reusable partials │ ├── head.html │ ├── header.html │ └── footer.html ├── _layouts/ # Page templates │ └── default.html ├── _posts/ # Blog posts (Markdown) ├── _sass/ # SCSS partials (optional) ├── assets/ │ ├── css/ │ │ └── style.css │ ├── js/ │ │ └── scripts.js │ └── images/ ├── _config.yml # Site config ├── Gemfile ├── Gemfile.lock ├── .gitignore ├── index.html # Home page └── README.md
Create the required files at the project root:
source 'https://rubygems.org'
gem 'jekyll', '~> 4.3'
gem 'jekyll-sitemap'
gem 'jekyll-seo-tag'
gem 'jekyll-relative-links'
gem 'webrick'
gem 'wdm', '>= 0.1.0', platforms: [:mingw, :x64_mingw, :mswin]
gem 'tzinfo'
gem 'tzinfo-data'
wdm,
tzinfo and tzinfo-data exist to keep
file-watching and time zones working correctly on Windows and JRuby. They are harmless on other
platforms because the gems are platform-gated.
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
.bundle/
vendor/
.DS_Store
Install the gems:
bundle install
3. Configure _config.yml
This file is the control centre of your Jekyll site. Every time you change it, you must restart the local server.
# ---------------------------------------------------------------------------
# Identity
# ---------------------------------------------------------------------------
title: My Jekyll Site
tagline: "Built with Jekyll, hosted on GitHub Pages"
description: A site built with Jekyll and hosted for free on GitHub Pages.
url: "https://username.github.io" # production domain - no trailing slash
baseurl: "" # "" for user sites, "/repo" for project sites
lang: en-NZ
locale: en_NZ
og_locale: en_NZ
timezone: Pacific/Auckland
# ---------------------------------------------------------------------------
# SEO / social metadata (consumed by jekyll-seo-tag)
# ---------------------------------------------------------------------------
title_separator: "|"
twitter:
card: summary_large_image
author:
name: Your Name
url: https://github.com/username
favicon: /assets/images/favicon.ico
# ---------------------------------------------------------------------------
# Single source of truth for outbound links
# Referenced in templates as {{ site.links.github }} etc.
# ---------------------------------------------------------------------------
links:
email: you@example.com
github: https://github.com/username
discord: https://discord.gg/xxxxxxxx
# ---------------------------------------------------------------------------
# Build behaviour
# ---------------------------------------------------------------------------
incremental: true
markdown: kramdown
kramdown:
input: GFM
hard_wrap: false
toc_levels: 2..6
syntax_highlighter: rouge # or: nil to render plain <code> blocks
sass:
style: compressed
quiet_deps: true
permalink: pretty
# ---------------------------------------------------------------------------
# Plugins (GitHub Pages whitelist)
# ---------------------------------------------------------------------------
plugins:
- jekyll-seo-tag
- jekyll-sitemap
- jekyll-feed
- jekyll-relative-links
relative_links:
enabled: true
collections: true
# ---------------------------------------------------------------------------
# Keep build/dev files out of the generated site
# ---------------------------------------------------------------------------
exclude:
- Gemfile
- Gemfile.lock
- node_modules
- vendor
- README.md
- LICENSE
- run.bat
# ---------------------------------------------------------------------------
# Collections
# ---------------------------------------------------------------------------
collections:
projects:
output: true
permalink: /projects/:path/
# ---------------------------------------------------------------------------
# Front matter defaults - apply top to bottom, later rules win
# ---------------------------------------------------------------------------
defaults:
- scope:
path: ""
values:
layout: "default"
image:
path: /assets/images/social-card.png
alt: "My Jekyll Site"
- scope:
path: ""
type: posts
values:
layout: post
permalink: /blog/:year/:month/:day/:title/
- scope:
path: "pages"
values:
permalink: /pages/:basename/
url and baseurl
must match how GitHub serves the site. For a user site
(username.github.io), baseurl should
be
empty. For a project site (username.github.io/repo), set it to
"/repo".
What each block actually does
-
url+baseurl- the two values every absolute link is built from. Getting these wrong is the single most common cause of "my CSS works locally but 404s on Pages". -
locale/lang/og_locale-langsets the<html lang>attribute,localeandog_localefeed SEO tags. Thexx_YYconvention matters for OpenGraph. -
timezone- an IANA identifier (Pacific/Auckland,Europe/London). Affects every Liquiddate:filter, including the copyright year in your footer. -
title_separator+twitter: card- formatting for the tags that{% seo %}emits. Set once, forget forever. -
links:- a single map of every outbound URL. Change a Discord invite in one place instead of hunting through twenty templates. -
kramdown.hard_wrap-falsefor hand-wrapped prose guides (single newlines are ignored);truewhen you want a single newline to become a<br>. -
kramdown.syntax_highlighter: nil- renders fenced code as plain<code>blocks with no colouring. Userougewhen you want highlighting. -
sass.style: compressed- minifies your SCSS output.quiet_depssilences deprecation warnings from third-party stylesheets. -
permalink: pretty- produces/about/instead of/about.html. -
exclude:- nothing here is secret (it's all still in the repo), but it keepsGemfile,node_modules/,vendor/and local scripts out of the published_site/. -
defaults:- front matter applied by scope. Rules are evaluated top to bottom and the last matching rule wins, so put your broadest rule first and your most specific rule last.
Plugin whitelist: jekyll-seo-tag,
jekyll-sitemap, jekyll-feed,
jekyll-relative-links and friends are all on GitHub's approved
list. If you build with GitHub Actions instead (see below), that list stops applying and you can
use any plugin you like.
If you're publishing a blog, add jekyll-feed to the plugin list - it
generates /feed.xml automatically. On a project repo you may also
want repository: and
github_username: at the top level, which some plugins and themes read
when building absolute GitHub links.
4. Layouts & includes
Layouts are the shells your pages get wrapped in. Includes are reusable snippets you drop inside layouts (or pages). Together they eliminate nearly all repetition.
<!DOCTYPE html>
<html lang="{{ site.lang | default: 'en' }}">
<head>
{% include head.html %}
</head>
<body>
<a class="skip-link" href="#main-content">Skip to content</a>
<header class="header">{% include header.html %}</header>
<main id="main-content">{{ content }}</main>
{% include footer.html %}
</body>
</html>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ page.title | default: site.title }}</title>
<meta name="description" content="{{ page.description | default: site.description }}">
{% seo %}
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
<nav class="main-nav">
<a href="{{ '/' | relative_url }}">Home</a>
<a href="{{ '/about/' | relative_url }}">About</a>
<a href="{{ '/blog/' | relative_url }}">Blog</a>
</nav>
<footer>
<p>© {{ site.time | date: '%Y' }} {{ site.title }}</p>
</footer>
Now any page can opt into the layout via front matter:
---
layout: default
title: Home
---
<h1>Welcome</h1>
<p>This page is rendered inside the default layout.</p>
{{ content }} is where each page's body
gets injected. {% include file.html %} pulls in a partial from
_includes/.
5. Data files
Any JSON, YAML, or CSV file inside _data/ is automatically available
in your templates. This is perfect for navigation menus, team lists, product catalogues, or any
content you'd rather keep separate from markup.
- title: Home
url: /
- title: About
url: /about/
- title: Blog
url: /blog/
- title: Contact
url: /contact/
Loop through it anywhere:
<ul>
{% for item in site.data.navigation %}
<li><a href="{{ item.url | relative_url }}">{{ item.title }}</a></li>
{% endfor %}
</ul>
_data/releases.json, which is generated by a GitHub Actions workflow.
Zero API calls from the visitor's browser.
6. Collections
Collections let you group related documents (projects, recipes, team members) and give them their own templates - a bit like pages, but managed together.
collections:
projects:
output: true
permalink: /projects/:path/
Create _projects/my-first-project.md:
---
layout: project
title: My First Project
---
A short description of the project goes here.
Render it from anywhere:
{% for project in site.projects %}
<a href="{{ project.url | relative_url }}">{{ project.title }}</a>
{% endfor %}
/:collection/:path/ keeps every
collection neatly namespaced, while /:name/ uses the filename. Pair
a collection with a scoped entry under defaults: so every document in
it gets the right layout automatically.
7. Local development
Jekyll ships with a built-in dev server with live reload:
bundle exec jekyll serve --livereload
Then open http://127.0.0.1:4000. Every saved change appears automatically.
Handy flags
--livereload # auto-refresh the browser
--drafts # include files in _drafts/
--future # include posts dated in the future
--unpublished # include posts marked published: false
--host 0.0.0.0 # expose the server to your LAN
--port 4001 # use a different port
--baseurl "" # override baseurl temporarily
These flags are identical on every platform - only the way you launch them tends to differ. A small launcher script saves a lot of typing:
@echo off
cd /d "%~dp0"
echo Cleaning site...
call bundle exec jekyll clean || exit /b
echo Starting Jekyll server on 127.0.0.1:4000 with live reload...
start cmd /k "cd /d "%~dp0" && bundle exec jekyll serve --livereload --host 127.0.0.1 --baseurl="
echo Waiting for server to start...
set "PORT=4000"
set "TIMEOUT=30"
for /l %%i in (1,1,%TIMEOUT%) do (
timeout /t 1 /nobreak >nul
netstat -an | find ":%PORT% " | find "LISTENING" >nul && goto :ready
)
echo WARNING: Server not responding after %TIMEOUT% seconds. Opening browser anyway.
:ready
start http://127.0.0.1:4000/
#!/usr/bin/env bash
set -e
cd "$(dirname "$0")"
if ! command -v bundle >/dev/null 2>&1; then
echo "Bundler not found. Install it first:"
echo " gem install jekyll bundler"
exit 1
fi
bundle exec jekyll clean
echo
echo "Starting Jekyll with live reload."
echo "Local address: http://127.0.0.1:4000"
echo "Press Ctrl+C to stop."
echo
bundle exec jekyll serve --livereload --open-url
Double-click run.bat, or run it from any terminal in the
project folder - it switches to its own directory first, so the working directory doesn't
matter. The script cleans the previous build, launches Jekyll in a separate console window,
polls the port for up to 30 seconds, then opens your browser once the server is
actually listening. Add run.bat to
exclude: in _config.yml
so it never ends up in _site/.
Make it executable once with chmod +x run.sh, then run
./run.sh. Add run.sh to
exclude: in _config.yml
so it never ends up in _site/.
Deploying with GitHub Actions
The easiest way to publish a Jekyll site is to let GitHub build it for you. You don't need to
commit the generated _site/ folder - a workflow builds it on
every push and deploys it.
-
Enable Pages
Go to Settings → Pages and set Source to GitHub Actions.
-
Add the deploy workflow
Create
.github/workflows/jekyll.yml:.github/workflows/jekyll.ymlname: Build and Deploy Jekyll Site on: push: branches: ["main"] workflow_dispatch: {} permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Ruby uses: ruby/setup-ruby@v1 with: ruby-version: "3.2" bundler-cache: true - name: Setup Pages id: pages uses: actions/configure-pages@v5 - name: Build with Jekyll run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" env: JEKYLL_ENV: production - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: "_site" deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 -
Push and watch
git add . git commit -m "Add Jekyll site" git push origin mainOpen the Actions tab on GitHub to follow the build. When it's green, your site is live.
Windows tip: if Git reports “LF will be replaced by CRLF” warnings, that's normal and harmless. If you'd rather not see them, add a.gitattributesfile with* text=auto eol=lf. -
Going further: a data-fetching workflow
You can also use Actions to generate data that Jekyll reads at build time. This project does exactly that - a scheduled workflow pulls GitHub Releases into
_data/releases.json, then triggers a rebuild..github/workflows/fetch-releases.yml (excerpt)on: schedule: - cron: "0 */6 * * *" # every 6 hours release: types: [published, edited] workflow_dispatch: {} permissions: contents: write jobs: fetch: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: { ref: main } - uses: actions/github-script@v7 with: script: | const fs = require('fs'); const releases = await github.paginate( github.rest.repos.listReleases, { owner: context.repo.owner, repo: context.repo.repo, per_page: 100 } ); fs.mkdirSync('_data', { recursive: true }); fs.writeFileSync('_data/releases.json', JSON.stringify(releases, null, 2)); - run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" git add _data/releases.json git diff --staged --quiet || git commit -m "chore: update data" git push
_site/
folder and point Pages at it. But Actions gives you reproducible builds, no local Ruby required, and
a clean repo. It's the recommended path.
Using a Custom Domain
You can serve your site from your own domain (e.g.
yourdomain.com) instead of the default
*.github.io address.
- Namecheap
- Cloudflare Registrar
- Porkbun
- Google Domains / Squarespace
Prices are typically $10-15/year for a .com.
In your repo root, create a file called CNAME (no extension)
containing just your domain:
yourdomain.com
Or, if you want the www subdomain:
www.yourdomain.com
At your registrar's DNS panel, add:
A records pointing to GitHub's IPs:
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
…or a CNAME record for www pointing
to:
username.github.io
Verify it worked
# Should return the GitHub Pages IPs
nslookup yourdomain.com
# PowerShell-native alternative with more detail
Resolve-DnsName yourdomain.com
# Should return a 200
curl.exe -I https://yourdomain.com
# Should show the TLS certificate details
curl.exe -vI https://yourdomain.com
# Should return the GitHub Pages IPs
dig +short yourdomain.com
# Should return a 200
curl -I https://yourdomain.com
# Should return your SSL certificate details
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null
Common Issues & Troubleshooting
Solutions:
- Repo must be named
username.github.io(for user sites) - Pages must be enabled under Settings → Pages
- You need an
index.htmlin the published folder - Wait 1-2 minutes after first enabling Pages
- Check the Actions tab for build failures
Solutions:
- Paths are case-sensitive on Linux servers
- Use
relative_urlin Jekyll:{{ '/assets/css/style.css' | relative_url }} - Hard-refresh the browser (Ctrl+F5 / Cmd+Shift+R)
- Open DevTools (F12) → Console for errors
Windows filesystems are case-insensitive. A file saved as
Style.css will load fine locally and then 404 on GitHub
Pages. Rename files in lowercase from the start.
Solutions:
- Builds take 1-2 minutes - wait and refresh
- Check the Actions tab for the latest run
- Clear browser cache or try an incognito window
- Confirm your branch is the one Pages is deploying from
Common causes and how to fix them:
- YAML syntax error - check
_config.ymland front matter for stray colons or tabs - Liquid tag mismatch - every
{% if %}needs a matching{% endif %} - Missing plugin - only plugins in this list are allowed with GitHub's hosted builder
- Case-sensitive paths -
Layouts/andlayouts/are not the same thing
Using the Actions workflow above sidesteps the plugin whitelist entirely, because the build runs on your own runner rather than GitHub's Pages builder.
- DNS propagation can take up to 48 hours
- Confirm the
CNAMEfile is in the published folder - Check for old A records pointing elsewhere
- Ensure you don't have conflicting
AAAArecords - Re-run your DNS lookup to confirm the IPs have updated
- Enable
incremental: truein_config.yml(local only) - Cache gems with
bundler-cache: truein Actions - Use
concurrencyin workflows to cancel outdated runs - Keep
_site/out of git via.gitignore
Debugging cheat-sheet
# Is the site reachable?
curl.exe -I https://username.github.io
# Where does the DNS point?
nslookup yourdomain.com
Resolve-DnsName yourdomain.com
# What certificate is being served?
curl.exe -vI https://yourdomain.com
# What does the local build produce?
bundle exec jekyll build --trace
# Serve with verbose output
bundle exec jekyll serve --verbose
# Is the site reachable?
curl -I https://username.github.io
# Where does the DNS point?
dig +short yourdomain.com
# What certificate is being served?
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null
# What does the local build produce?
bundle exec jekyll build --trace
# Serve with verbose output
bundle exec jekyll serve --verbose
Prefer the Unix tools? Git Bash (installed with Git for Windows) gives you
dig, openssl and a real
curl - the Linux column above works verbatim inside it.
Resources & Further Learning
Next Steps
- Use Jekyll for blogging (
_posts/) - Add Google Analytics or Plausible
- Wire up a contact form (Formspree, Netlify Forms)
- Create a custom
404.html - Add an RSS feed via
jekyll-feed - Enable
jekyll-seo-tagandjekyll-sitemap - Turn the site into a PWA with a
manifest.json, icon set, and a service worker
- Always work on a branch, merge via PR
- Test locally before pushing
- Keep
_site/out of Git - Use GitHub Actions for CI/CD
- Learn responsive design with
clamp()and CSS grid - Prefer
relative_urlfilters to hard-coded paths - Route every outbound link through
site.linksso URLs change in one place