How To Use GitHub Pages To Make Web Sites While Learning Code

People use GitHub to host projects ranging from music composition to cookbooks to municipal data. But what you might not know is that GitHub isn’t just a storage locker, but also a showcase. That is, GitHub allows you to set up a bare-bones website you can use to display projects and collaborate.

Welcome to GitHub Pages, the glossy, forward facing side of the site. Unlike the dense repositories that would confuse your less tech-savvy friends, Pages are ordinary looking websites that GitHub hosts for free.

GitHub Pages, which are a bit like Git with training wheels, let you explore repository building without ever leaving the website. No command line coding here: GitHub Pages lets you make a documented change, or "commit," to the site simply by clicking “OK.”

GitHub's Matthew McCullough spends his time traveling the world teaching students to use Git and GitHub. He said that people who want to explore basic coding and collaborative concepts without having to get in too deep are ideal candidates for GitHub Pages.

“[Some people] want to click a button, get a themed template on WordPress, and they’re fine,” he said. “But I’ve noticed more and more people want to get their feet wet and understand what code is, and Pages is their gateway.”

Why Use Pages?

If you’re looking for an out-of-the-box website, Pages isn’t that, though McCullough hopes that the service will eventually have more user-friendly options. 

Right now, people choose to use Pages for the same reason they choose to use GitHub—it’s ideal for collaboration. All Pages blogs are open source, so anyone can view the repository side of the site, look for bugs, and submit a pull request to the user. Of course, nobody can alter the site except the owner, who can choose to approve these pull requests or not.

As an example, McCullough shows off the GitHub Teaching site. From the Pages side, it’s spartan, but familiar. But from the back side, it’s a repository where students can learn by making edits to the very site that’s helping them learn.

“Culturally, why would people choose this?” McCullough posits. “It’s nerdy and sticky and less polished. But I would say the ability for people to find a public website and make contributions that then get recorded with their name on it makes it worth it. Open source, open culture.”

And of course, the fact that anything you put on GitHub remains always and entirely your own property and copyright doesn’t hurt. (See Section F of the GitHub Terms of Service.)

However, even with all of the resources McCullough’s team has provided, GitHub Pages won’t hold your hand. Participants will need to have GitHub user accounts and a moderate understanding of HTML. 

Setting Up Your First Page

If you have a GitHub account, your first Page already exists—it just doesn’t have anything on it yet. That’s why you need to choose your GitHub username carefully. When you sign up for GitHub, automatically yourname.github.io is reserved for you. 

That’s your top page. But you can have as many GitHub Pages as you want. Just create other repositories. For example, yourname.github.io/blog. GitHub differentiates this by calling the former a User Page, and the latter a Project Page. 

“You can have one repository that will publish at that top level page,” said McCullough. “It makes a great home page, resume, bio, or primary site. Then, you can build sub-sites that center on interests or a blog.”

In order to create this first, main page, you’ll need to create a new repository. Go to your GitHub user page, tab over to Repositories, and click the green “New” button. 

The name of your new repository must be yourname.github.io, or else the Pages generator won't work. So for me, that's laurenorsini.github.io. Later, if I want to change it to something else like www.lorsini.com, I can redirect a domain name. But this is still where the site will live.

On the new repository’s page, click on the Settings icon in the lower right-hand corner.

Scroll down until you see GitHub Pages, right under Features. Click “Automatic Page Generator.”

GitHub will automatically populate your homepage with a lot of helpful advice about using Pages. You can leave this for now. Click the “Continue to Layouts” button at the bottom of the page.

There are only a few to choose from so far. Pick the one you like best. Keep in mind that it’ll be difficult to change it later. If you make changes to one theme and then decide on another, you’ll lose those changes. Luckily, this is GitHub. Every time you commit a change, there’s the option to revert back to any commit in the page’s history.

Navigate to yourname.github.io. It may take up to ten minutes, but your page will be live. 

Editing Your First Page

In order to update the page’s content, go back to the repository (you can also click the “View on GitHub” button on your page) and navigate to Index.html. 

Now, it’s time to edit the raw code. I recommend GitHub’s built-in Zen mode, which causes the editor to take up your entire screen. You can also replace everything here with code you've written previously on your computer. 

When you’re done, finalize your changes with the “Commit Changes” button. In up to ten minutes, you’ll see those changes live. 

If you want to do anything more advanced, like add images or CSS, you’ll need to make a copy of your page on your computer. You’ll also need to have GitHub for Mac or GitHub for Windows

In the lower right-hand corner of the repository page, click “Clone in Desktop.” This will save a copy of your repository in the top-level folder on your computer. It will also open up your copy of GitHub for Mac or GitHub for Windows.

Find the repository folder by searching your computer, or by looking in the top-level folder. It will, of course, be named yourname.github.io

I want a headshot on my GitHub Pages home page, so I dragged and dropped a photo I already had into the folder. 

Then I committed the change on GitHub for Mac. I pressed “Sync Commits” so this change would be reflected on GitHub as well as on my computer. You'll see in the photo, it says "No unsynced commits" once everything is online.

Finally, I edited the code of Index.html to add a photo with HTML:

<img align="left" src="identity_square.jpg" width="250" height="250" />

I can see the purists cringing since I really should have adjusted the height, width, and alignment in the CSS to reduce bloat, but I’m just trying to show you the easiest possible process. 

You can view the changes live on my page

Of course, this page is far from done. Are you a Pages user? I’d love to see your page linked in the comments.