GitHub Pages

💡 The Concept

GitHub Pages free hosting lets you publish a static website directly from a GitHub repository at no cost. GitHub Pages lets you host a fully functional website for free, directly from your GitHub account. No credit card, no hosting bill, no server setup. Your URL follows this format:

username.github.io/projectname

As a bonus, using GitHub introduces you to Git — a version control system that is one of the most in-demand skills in software development.

What You Will Need

• A free GitHub account at github.com
• Your completed website files, with your home page named index.html

About GitHub

GitHub.io is a place where developers share code. Most developers have a GitHub account, where they share examples of their work with others and collaborate on projects.

GitHub uses Git for version control. All large companies have some mechanism for version control of their software — some use GitHub, others use tools like Atlassian BitBucket or GitLab. In a typical workflow:

• Developers check out code when they work on it.
• When new code is approved, it is merged into the company’s codebase.

Learning Git in depth is outside the scope of this class. However, Git is a very desirable skill when looking for a first programming job. Learn more about Git at TutorialsPoint.

Exercise: Try It Yourself

These instructions are adapted from a procedure written by Darren Pearson.

Throughout these instructions, two placeholders are used. Replace them with your own information:

• USERNAME — your GitHub username (the “owner” of the repository)
• PROJECTNAME — the name you give your repository

A. Create a GitHub Account — Only needed once

1. Go to github.com and click Sign up.
2. Enter your email address and click Continue.
3. Create a password and click Continue.
4. Enter a username. If it is already taken, GitHub will suggest alternatives. Click Continue.
5. Type y or n when asked about email updates, then click Continue.
6. Complete the verification puzzle, then click Create account.
7. GitHub will send a launch code to your email. Open your email, find the message from GitHub, and enter the code on the page.
8. GitHub may ask a few questions about how you plan to use it. Answer them or click Skip personalization. Either way, you will land on your GitHub dashboard.

B. Create a Repository — Repeat for each project

1. Save your website. Make sure your home page is named index.html. You can only host HTML projects on GitHub Pages.
2. In GitHub, click the Create repository button on your dashboard, or click the + icon in the upper right and choose New repository.
3. Under Repository name, enter your PROJECTNAME. Add a description, choose Public, and check Add a README file. Click Create Repository.
   Note: If you are making a portfolio website, use USERNAME.github.io (your GitHub username followed by .github.io) as the repository name — not just your username by itself. That way your site will be at username.github.io. See the note at the bottom of this page.
4. The URL should now read: https://github.com/USERNAME/PROJECTNAME

C. Create the gh-pages Branch

1. Click the main branch dropdown, type gh-pages, then click Create Branch.
2. Make sure the branch switches to gh-pages before continuing.

Note: You create the branch by clicking the Create branch: gh-pages from ‘main” link as shown in the screenshot.

D. Upload Your Files

1. Click Add file → Upload files.
2. Open your project folder on your desktop. Drag index.html into the “Drag files here” area in your browser.
   Note: Do not drag the project folder itself — index.html must be at the root of the repository.
3. Drag your images folder into the same area. Drag the folder itself — not the individual files inside it — so that GitHub preserves the folder structure your HTML file expects.
4. Verify all files are listed, confirm Commit directly to the gh-pages branch is selected, then click Commit changes.
5. Open a new tab and go to USERNAME.github.io/PROJECTNAME to check your live site. The first time can take 5–10 minutes to go live. If the page is not showing after 10 minutes, go to your repository’s Settings → Pages and confirm that gh-pages is selected as the source branch.

What to Do If Your Images Don’t Show Up

When many students first publish to GitHub or to a hosting server, the images do not appear. This happens more often on Windows. The reason is that Windows browsers are not case sensitive — but web servers are. A file named Logo.jpg and one named logo.jpg are the same on Windows but different on a server.

1. Make sure your image file names match exactly in both the src attribute (e.g. src="images/logo.jpg") and in the images folder. By convention, image names should be all lowercase with dashes between words. For your final project, all file and folder names must be lowercase.
2. Check that your images folder is at the same level as your index.html file — not inside another folder. If you are unsure how files and folders work together on the web, this blog post explains it well: Understanding How Websites Work with Files and Folders. Understanding file structure is critical to web development and to all programming.

Creating a Homepage Repository on GitHub

The procedure above creates a project page at username.github.io/projectname. Some GitHub users also create a personal homepage — a short bio with links to their projects — at a shorter URL: username.github.io.

To do this, follow the same procedure above but set PROJECTNAME to USERNAME.github.io (using your actual username). This special repository is automatically served at https://USERNAME.github.io. Note that this homepage sometimes takes longer to go live — wait up to five minutes before checking.

Common mistake: The repository name must be your full username followed by .github.io — for example, kionayang18.github.io. If you create a repository named just your username by itself (e.g. kionayang18, with no .github.io), GitHub does not treat it as a Pages site. Instead, that exact repo name triggers a different, unrelated GitHub feature: the profile README (the “About me” section shown on your profile page). Your homepage will not appear at the root URL. If your homepage isn’t showing up, go to your repository and double-check that its name is spelled exactly right, including .github.io.

❓ Frequently Asked Questions

★ Key Takeaways

GitHub Pages is a free way to publish a website straight from your code repository. This lesson showed you how to set up a repo and turn it into a live, publicly accessible site. That wraps up the Website Publishing category. You now have everything you need to get a website on the internet, whether through GitHub Pages or through a paid domain and hosting setup.

← Back to Website Publishing Lessons

← Back to All Lessons