In part two of this series, we explored getting your GitHub Pages site setup using one of the official GitHub Pages themes. If you’ve followed along this far, this means you have a functioning, themed GitHub Pages site. Great! Now, let’s dig a little deeper.
Picture this: you’re building a new GitHub Pages site and after a lot of work, you have everything the way you want it. You hit the green “Commit changes button” in GitHub’s file editor, excited for GitHub to publish your site. However, when you go to visit your GitHub Pages site you find a 404 error page. Shortly after, you get an email from GitHub with a subject that reads:
[nickcannariato/nickcannariato.github.io] Page build failure
If you’ve ever experienced this, you know that it can be frustrating. Everything works when you look at the site on your own machine, so you don’t even know where to begin trying to fix the problem. Eventually, after exhaustively searching the web for anything you can think of, you email GitHub for help. There has to be a better workflow, right?
Well, the GitHub Support team has good news for you: there is! The solution to this problem is testing your site locally using the GitHub Pages gem, a Ruby gem used to set up and maintain a local Jekyll environment in sync with GitHub Pages. The GitHub Pages gem matches your local environment to GitHub Pages and helps you catch errors before you push your site to GitHub.
Today we’ll walk you through cloning your GitHub Pages site to your computer and using the GitHub Pages gem to build and test your site.
Before you get started
This guide requires that you set a few things up on your own before getting started. The specific requirements are as follows:
- You’ve completed the first two guides in this series (if not, here you go: Part one, Part two)
- You’ve installed Git
- You have a text editor (I recommend Atom)
- You’ve installed both Ruby and the Bundler gem
- (Optional) You’ve installed GitHub Desktop
Once you’ve completed the previous guides and installed the necessary software, you’re ready to begin.
Step one: Clone your repository
In this series, we’ve been creating and editing our site in the web browser using GitHub’s file editor. But as your site gets more complex, it might be much better for you to develop your GitHub Pages site locally. The great news is that since GitHub Pages site’s are Git repositories, they’re designed to be used this way.
Step two: Install GitHub Pages’ dependencies
Once the repository has been cloned to your computer, open it up in your text editor of choice. If you’re using Atom, you can find instructions for opening directories in the “Flight Manual.”.
Assuming you’re working with the repository we’ve been using throughout this series, your local repository should have the following files in it:
| | - index.md | - README.md | - _config.yml
As a refresher: the index.md file is used as the main page of your GitHub Pages site, the README.md file is used as the front page of your repository on GitHub, and the _config.yml file is used to configure Jekyll’s settings.
Having the files locally is great, but if we want to actually build and test our GitHub Pages site we’ll need to install the GitHub Pages gem](https://github.com/github/pages-gem). Step 2 of “Setting up your GitHub Pages site locally with Jekyll” will walk you through creating a Gemfile and installing your dependencies using Bundler.
Step three: Build your site
Once Bundler installs your dependencies, you’re ready to build your site. To do this, you’ll need to open the the appropriate command line application (Terminal on macOS and Linux, Git Bash or Powershell on Windows), navigate to your local repository, and then serve your site locally by running the command in step 4 of “Setting up your GitHub Pages site locally with Jekyll”.
Step four: You’re done!
That’s it! After you run the command to serve your GitHub Pages site with Jekyll, your terminal will either output the errors it encountered while generating your site, or it will tell you that your site was generated and point to the site’s URL.
Conclusion & next steps
Congrats! You’ve just set up a local development environment for GitHub Pages! Now you can work on your site, test it for errors, and deploy it to GitHub Pages knowing that your Pages site will publish as expected. Be on the lookout for the next part in our series where we’ll talk about customizing the HTML and CSS of your chosen theme.
Finally, as always, I’ve provided some resources that will help you level up your GitHub Pages skills: