Link Search Menu Expand Document
GitHub How-tos

Building Locally

Overview

This document walks through the process of building your pre-existing GitHub Pages repo on your local machine. This is advantageous as this allows you to preview changes instantly instead of committing and pushing the changes, then waiting on GitHub to build the site for you.

Installation of Dependencies

There are several pieces of software that you will need to get your repo up and running locally. You will need:

  • Git.
    • Note: Having the Git Desktop application installed on your machine isn’t sufficient!
  • A version of the Ruby programming language.
  • The Bundler package manager for Ruby.
  • The Jekyll Ruby package.

Installing Git

Windows

To install Git for Windows, click the download link at this site and run the installer once downloaded. There are quite a few options that you can choose to customize your experience with using Git. However, we recommend keeping everything default except for the editor of choice for Git (the first option you are presented to change). Using Visual Studio Code as your editor of choice is much easier than using the default Vim editor.

This installs Git along with the ‘Git Bash’ shell that allows us to build the website locally.

Linux

To install Git for your Linux distribution, use your package manager.

Ubuntu

From your shell, install Git using apt-get:

$ sudo apt-get update
$ sudo apt-get install git

Installing The Ruby Language

Windows

To install the Ruby programming language, visit this site to download the Ruby installer. There are many options on which installer to download but they keep their updated recommended installer to the right of the installer links under the “Which Version to Download?” section.

Once the installer has downloaded, run it and follow the prompts. On the last step of the installation wizard, be sure to run the ridk install step. This is important for installing the Ruby packages we need.

Linux

To install Ruby for you Linux distribution, use your package manager.

Ubuntu

From your shell, install Ruby using apt-get:

$ sudo apt-get install ruby-full

Installing Bundler

Ruby packages come as “gems” much like how Python packages come as modules. A convenient package manager for the Ruby language is Bundler.

Windows

Per Bundler’s website, to install Bundler:

  1. Open a Git Bash window on your local machine. To do this:
    1. Click the Windows icon on the lower left of your screen to open the Start Menu.
    2. Search for “Git Bash” and hit Enter.
  2. Type the following in the Git Bash window: 
     gem install bundler

    Ruby will install Bundler for you and notify you when it has finished. Keep the Git Bash window open for the next step.

Linux

  1. Open a shell on your local machine.
  2. Type the following in the terminal window: 
     gem install bundler
    • Note: you may have to use sudo for this command.

    Ruby will install Bundler for you and notify you when it has finished. Keep the terminal open for the next step.

Installing Jekyll

Jekyll is a Ruby gem that converts markdown files into HTML pages for websites. To install Jekyll, type the following into a the Git Bash or terminal window you have open from the previous step:

gem install jekyll
  • Note: you may have to use the sudo command if you are on a linux machine.

As with Bundler, Ruby will notify you when the installation has finished.

Finally, verify that Jekyll has installed correctly by typing, jekyll -v in the Git Bash or terminal window.

Setting Up The Repo to Build Locally

Now that the installation of all the dependencies are taken care of, we can focus on constructing the additional file we need to build our GitHub Pages website locally.

The Gem File

This additional file is named Gemfile and is how we tell Ruby that we need the GitHub Pages gem before we can build the website.

To construct this file, open your favorite text editor, create a new file named Gemfile (no file extension), and type the following:

source 'https://rubygems.org'
gem "github-pages", group: :jekyll_plugins

Save the Gemfile in the same directory as the _config.yml and index.md file of your GitHub Pages repository.

Building the Repo Locally

Now that we have all of the dependencies installed and the Gemfile made, we can finally build our website locally. To do so:

  1. Open a Git Bash or terminal window.
  2. Navigate to the directory that contains your _config.yml, index.md, and Gemfile files.
  3. If this is your first GitHub Pages site that you are building locally, type the following in your Git Bash or terminal window: 
     bundle install

    This installs all of the gems necessary to build your site locally (these were specified via the Gemfile).

    If this is not your first GitHub Pages site that you are building locally, you can skip this step.

  4. Type the following in your Git Bash or terminal window: 
     bundle exec jekyll serve

    This will initiate the build process for your website and will inform you what port the website is located at. This is nearly always localhost:4000.

    • Note: if you want to build more than one GitHub Pages site at once, you’ll have to specify a different port for each one. The first site that you build will use localhost:4000 but you’ll need to specify a new port for each subsequent site you want to build by adding the --port command line option when you build the site, like so: 
        bundle exec jekyll serve --port=XXXX

      where XXXX is the port number you would like to specify.

  5. Open an internet browser and type in the address bar localhost:XXXX where XXXX is the port number you were given in the previous step. If everything has gone right, you should now see your GitHub Pages website just like how it is built when pushed to GitHub.