How to Create a Website with GitHub Pages 

-> Download the Guide

GitHub Pages is a free service from GitHub that lets you host a website directly from your files. No server setup, no monthly fees — just upload your files and your site is live on the internet within minutes. This guide will walk you through every step from scratch

Setup

Step 1

Create a free GitHub account

Go to github.com and click ‘Sign up’. Follow the prompts to create your account. You will need to:

  • Enter your email address
  • Create a username — this will appear in your website address, so choose something you are happy with
  • Set a password
  • Verify your email address by clicking the link GitHub sends you

✦

TipYour website will live at yourusername.github.io — so your username matters. Keep it professional if you plan to share the site.

Step 2

Create a new repository

A repository (often shortened to ‘repo’) is like a folder that holds all your website files. Once logged in to GitHub:

  • Click the green ‘New’ button on your dashboard, or navigate to github.com/new
  • In the ‘Repository name’ field, type exactly: yourusername.github.io — replacing ‘yourusername’ with your actual GitHub username
  • Make sure ‘Public’ is selected (not Private) — GitHub Pages requires public repos on free accounts
  • Click the green ‘Create repository’ button

✦

TipThe repository name must match your username exactly, including lowercase letters. For example, if your username is ‘janedoe’, the repo must be named janedoe.github.io.

Part 2

Create Your First Page

Step 3

Create your homepage file

In your new repository, click the link that says ‘creating a new file’. In the filename box at the top, type:

index.html

This is your homepage. When someone visits your website address, GitHub will automatically show them this file first.

Step 4

Add HTML content

In the large text area below the filename, paste the following starter code:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
    <p>Welcome to my website.</p>
  </body>
</html>

Feel free to change the text between the tags to say whatever you like. The text between <title> tags appears in the browser tab, and <h1> creates a large heading on the page.

Step 5

Save your file

Scroll down to the bottom of the page. You will see a section called ‘Commit changes’. Click the green ‘Commit changes’ button to save your file. Think of this like hitting Save in a word processor — it stores your file in the repository.

Part 3

Enable GitHub Pages

Step 6

Turn on GitHub Pages

Now you need to tell GitHub to publish your repository as a website:

  • In your repository, click ‘Settings’ in the top menu bar
  • In the left sidebar, click ‘Pages’
  • Under the ‘Source’ section, click the dropdown and select ‘Deploy from a branch’
  • In the branch dropdown, select ‘main’
  • Click ‘Save’

Step 7

Wait for your site to go live

GitHub needs a moment to build and publish your site. This usually takes between 1 and 3 minutes. Refresh the Settings > Pages page and you will see a green banner with your live URL when it is ready.

✦

TipIf the site does not appear after a few minutes, try a hard refresh in your browser: press Ctrl+Shift+R on Windows/Linux, or Cmd+Shift+R on Mac.

Part 4

Visit and Update Your Site

Step 8

Open your website

Your site is now live on the internet! Open a browser and go to:

https://yourusername.github.io

You should see the page you just created. Share this link with anyone — it works like any other website address.

Step 9

Make updates

Updating your site is simple. Any time you want to make a change:

  • Go to your repository on GitHub
  • Click on the file you want to edit (e.g. index.html)
  • Click the pencil icon (Edit) in the top right corner of the file
  • Make your changes
  • Scroll down and click ‘Commit changes’
  • Wait 1–2 minutes, then refresh your live site

Every commit you make automatically triggers a new build of your site. There is no separate ‘publish’ step.

Part 5

Adding Free Themes

GitHub Pages has built-in support for Jekyll, a tool that automatically applies themes and layouts to your site. You can give your site a polished, professional look without writing any CSS yourself.

Option A — Use the GitHub Theme Picker (easiest)

GitHub has a built-in theme chooser that lets you preview and apply themes with one click:

  • Go to your repository and click ‘Settings’
  • Click ‘Pages’ in the left sidebar
  • Click ‘Choose a theme’ (this button may appear as ‘Change theme’ if you have already set one)
  • Browse the available themes and click one to preview it
  • When you find one you like, click ‘Select theme’
  • GitHub will automatically create a configuration file in your repo

✦

TipThemes in the picker include: Architect, Cayman, Dinky, Hacker, Leap Day, Merlot, Midnight, Minima, Minimal, Modernist, Slate, Tactile, and Time Machine.

Option B — Apply a theme manually using _config.yml

For more control, you can set a theme by creating a configuration file yourself. In your repository, create a new file called:

_config.yml

To use one of GitHub’s built-in supported themes, add this line to the file:

theme: jekyll-theme-cayman

Other valid built-in theme values:

theme: jekyll-theme-architect
theme: jekyll-theme-dinky
theme: jekyll-theme-hacker
theme: jekyll-theme-leap-day
theme: jekyll-theme-merlot
theme: jekyll-theme-midnight
theme: jekyll-theme-minimal
theme: jekyll-theme-modernist
theme: jekyll-theme-slate
theme: jekyll-theme-tactile
theme: jekyll-theme-time-machine

Commit the file, wait a minute, and your site will reload with the new theme applied.

Option C — Use a remote theme from GitHub (more options)

You can also use thousands of free Jekyll themes from GitHub that are not in the built-in picker. Find themes at jekyllthemes.org or jekyllthemes.io. To use a remote theme, update your _config.yml to include:

remote_theme: owner/repository-name

plugins:
  - jekyll-remote-theme

For example, to use the popular Minimal Mistakes theme:

remote_theme: mmistakes/minimal-mistakes

ℹ

NoteRemote themes may have their own setup requirements. Always check the theme’s README on GitHub for any extra steps needed.

Converting your page to work with Jekyll themes

Most Jekyll themes expect your pages to use a ‘front matter’ header. Open your index.html file and add these lines at the very top (above the <!DOCTYPE html> line):

---
layout: default
title: Home
---

The three dashes mark the start and end of the front matter block. The ‘layout’ value tells Jekyll which template from the theme to use. Most themes include a ‘default’ layout — check your theme’s documentation for other available layout names.

Using Markdown instead of HTML (optional)

Jekyll also lets you write your pages in Markdown, which is much simpler than HTML. Rename your index.html to index.md and write plain text with simple formatting:

---
layout: default
title: Home
---

# Welcome to my site

This is a paragraph of text.

- Item one
- Item two
- Item three

Jekyll will automatically convert this to a styled HTML page using your chosen theme.

Quick Reference

Here is a summary of the key files and what they do:

File Purpose Required?
index.html Your homepage Yes — this is the main page
index.md Homepage in Markdown (alternative to index.html) Use one or the other
_config.yml Jekyll configuration and theme settings Only if using themes
style.css Custom styling for your site No — optional
about.html An example of an additional page No — optional

Next Steps

Once your site is up and running, here are some things you can explore to take it further:

  • Learn basic HTML and CSS
  • Add more pages by creating additional .html files in your repository
  • Add images by uploading them to your repo and referencing them with an <img> tag
  • Use a custom domain name (e.g. www.yourname.com) — GitHub Pages supports this for free
  • Explore free Jekyll themes at jekyllthemes.org for more design options
  • Learn about GitHub’s version history to track and undo changes to your site