GitHub Pages

Put an HTML, CSS and JavaScript website online straight from a repository, and update it with every push.

Lesson 14 of 30Intermediate16 min read

You've built a web page. Now you want anyone in the world to be able to open it. GitHub Pages publishes a website directly from a GitHub repository: you push your HTML, CSS and JavaScript files, and GitHub serves them at an address like https://samlee.github.io/portfolio/.

It's ideal for portfolios, project demos, documentation and small websites, and it's included with every GitHub account. Once it's set up, updating the live site is as simple as committing and pushing; GitHub republishes automatically within a minute or two.

In this lesson you'll prepare a project for publishing, turn on GitHub Pages, find your site's address, update it, and fix the problems beginners most often hit. If you haven't built a page yet, start with the HTML tutorial.

What GitHub Pages can host

GitHub Pages serves static files: HTML, CSS, JavaScript, images, fonts and similar. Everything that runs in the browser works, including the projects from our HTML, CSS and JavaScript courses.

It can't run server-side code such as PHP or Python, or host a database. For those you'd use a hosting service that runs a server. Public repositories can use Pages on every plan; private repositories need a paid plan.

Preparing your project

  • The home page must be called index.html and sit in the top folder of the repository (or in a docs folder, if you choose that option).
  • Use relative paths for your files: css/style.css and images/logo.png, not C:/Users/sam/site/css/style.css.
  • File names are case-sensitive online. Logo.png and logo.png are different files, even if your computer treats them as the same.

Turning on GitHub Pages

  1. Push your project to a repository on GitHub.
  2. Open the repository's Settings tab and choose Pages in the sidebar.
  3. Under Build and deployment, set Source to Deploy from a branch.
  4. Choose the branch, usually main, and the folder, / (root), then click Save.
  5. Wait a minute, then refresh. GitHub shows your site's address at the top of the Pages settings.

Your address is https://username.github.io/repository-name/. If you name a repository exactly username.github.io, it becomes your main site at https://username.github.io/.

Updating and custom domains

To change the live site, edit your files, commit and push as usual:

Terminal
git add .
git commit -m "Add projects section"
git push

The Actions tab shows each publishing run. When it finishes, refresh your site (sometimes with Ctrl + Shift + R to skip the browser's cache).

You can also use your own domain, such as www.samlee.dev: enter it under Custom domain in the Pages settings and add the DNS records GitHub lists at your domain registrar. Tick Enforce HTTPS once it's available.

GitHub Pages Syntax

Publishing steps

git add .
git commit -m "Describe the update"
git push
# Settings > Pages > Deploy from a branch > main / (root) > Save
# Site: https://<username>.github.io/<repository>/

GitHub Pages Summary

  • GitHub Pages hosts static websites (HTML, CSS, JavaScript) from a repository.
  • The home page must be index.html; use relative, correctly-cased paths.
  • Turn it on in Settings, Pages, by choosing a branch and folder.
  • Your site lives at username.github.io/repository-name.
  • Every push to that branch republishes the site automatically.

GitHub Pages Examples

Each example shows the code, the output it produces and what each part does.

Example 1

A project ready to publish

Text
portfolio/
├── index.html
├── about.html
├── css/
│   └── style.css
└── images/
    └── me.jpg
Output
https://samlee.github.io/portfolio/            -> index.html
https://samlee.github.io/portfolio/about.html  -> about.html
https://samlee.github.io/portfolio/css/style.css
Line-by-line explanation
  1. Line 2index.html in the top folder becomes the home page.
  2. Line 3Other pages are available at their own file names.
  3. Lines 4 to 7Folders keep the same structure online.
Example 2

Relative paths in index.html

HTML
<!DOCTYPE html>
<html lang="en">
<head>
  <title>Sam Lee | Portfolio</title>
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <img src="images/me.jpg" alt="Sam smiling at the camera">
  <a href="about.html">About me</a>
</body>
</html>
Output
Works the same on your computer and on GitHub Pages,
because every path is relative to index.html.
Line-by-line explanation
  1. Line 5css/style.css is found next to index.html, wherever the site is hosted.
  2. Line 8The same goes for images.
  3. Line 9Links between pages use file names, not full addresses.
Example 3

Publish an update

Terminal
git add index.html
git commit -m "Add projects section"
git push
Output
[main 91b7e3c] Add projects section
 1 file changed, 22 insertions(+)
To https://github.com/samlee/portfolio.git
   7c2d91a..91b7e3c  main -> main
Line-by-line explanation
  1. Line 3Pushing to main starts a new publishing run. The Actions tab shows its progress, and the live site updates when it completes.

Common GitHub Pages Mistakes

Home page with the wrong name

Don't
portfolio/
  home.html
Do
portfolio/
  index.html

GitHub Pages looks for index.html. Without it, the site address shows a 404 page.

Absolute paths from your computer

Don't
<link rel="stylesheet" href="C:/Users/sam/portfolio/css/style.css">
Do
<link rel="stylesheet" href="css/style.css">

The C: path only exists on your computer, so the live site loads without styles.

Mismatched capital letters

Don't
<img src="images/Me.JPG" alt="Sam">
<!-- the file is images/me.jpg -->
Do
<img src="images/me.jpg" alt="Sam">

Windows and macOS ignore the difference, but GitHub's servers don't.

GitHub Pages in Real Projects

Sites on GitHub Pages

Developers host portfolios and CVs on Pages, open-source projects publish their documentation there, and conference and event sites often use it too. Because each update is a commit, the whole history of the site is saved, and any previous version can be restored with Git.

GitHub Pages FAQ

Is GitHub Pages free?

Yes, for public repositories on the free plan. Publishing a Pages site from a private repository requires a paid plan. Either way, the published site itself is public unless your organization uses an enterprise plan with access control.

How long does it take for GitHub Pages changes to appear?

Usually a minute or two, though it can take up to around ten minutes. Each publish runs as a workflow, so check the repository's Actions tab to see whether it finished or failed. A hard refresh in your browser helps if you're seeing a cached copy.

What is the .nojekyll file for?

When you publish from a branch, GitHub Pages runs your files through Jekyll, which skips files and folders whose names start with an underscore. Adding an empty file named .nojekyll to the published folder turns that processing off, so folders such as _next or _assets are published.

Can I have more than one GitHub Pages site?

Yes. You get one user site at username.github.io from a repository with exactly that name, and every other repository can have its own project site at username.github.io/repository-name. Organizations work the same way.

Can I password-protect a GitHub Pages site?

Not on the free or standard paid plans: Pages sites are public, even when the repository is private. Only organizations on an enterprise plan can limit who can view a Pages site. Never put secrets or private data on a Pages site.

GitHub Pages Exercises

Answer each one and check it instantly. If you get stuck, open the hint before the answer.

Fill in the blankseasy

Complete the name of the file GitHub Pages uses as the home page.

.html
Multiple choiceeasy

Which of these can GitHub Pages host?

Predict the outputmedium

User ada publishes the repository recipes with GitHub Pages. What's the site's address?

Multiple choicemedium

How do you update a published GitHub Pages site?

Multiple choicehard

Your Pages site shows a 404. What should you check first?

GitHub Pages Quiz

5 questions to check what you learned.

  1. Where do you turn on GitHub Pages?

    • In the Issues tab
    • In your profile README
    • In the terminal only
    • In the repository's Settings, under Pages

  2. Why should you use relative paths like css/style.css?

    • They load faster
    • They work both on your computer and on the published site
    • GitHub requires short file names
    • They hide your files

  3. What does naming a repository username.github.io do?

    • Publishes it as your main site at https://username.github.io/
    • Makes it private
    • Deletes your other sites
    • Creates a custom domain

  4. Your site works locally, but on GitHub Pages one image is missing. What's the most likely cause?

    • GitHub Pages doesn't support images
    • The image is too old
    • The capital letters in the file name don't match the HTML
    • You need a custom domain

  5. What kind of website can GitHub Pages host?

    • Sites that need a PHP server
    • Static sites made of HTML, CSS, JavaScript and images
    • Sites with their own database
    • Only Markdown files

Related GitHub topics

15GitHub ActionsAutomate testing, checks and deployments with GitHub Actions workflows written in YAML.06Push, Pull & CloneConnect a local repository to GitHub, push your commits, pull others' changes and clone repositories.
Esc
↑↓ to navigateEnter to open