Setting up your GitHub Pages site locally with Jekyll

You can set up a local version of your Jekyll GitHub Pages site to test changes to your site locally. We highly recommend installing Jekyll to preview your site and help troubleshoot failed Jekyll builds.

Note: You can skip this step if you would rather use the master branch for your Project Page. If you haven't checked out any branches, once you make a commit in your local repository, your change will appear on the master branch by default.

git checkout -b gh-pagesSwitched to a new branch 'gh-pages'# Creates a new branch called 'gh-pages', and checks it out

Tip: If you see a Ruby error when you try to install Jekyll using Bundler, you may need to use a package manager, such as RVM or Homebrew, to manage your Ruby installation. For more information, see Jekyll's troubleshooting page.

Step 3 (optional): Generate Jekyll site files

To build your Jekyll site locally, preview your site changes, and troubleshoot build errors, you must have Jekyll site files on your local computer. You may already have Jekyll site files on your local computer if you cloned a Jekyll site repository. If you don't have a Jekyll site downloaded, you can generate Jekyll site files for a basic Jekyll template site in your local repository.

If you want to use an existing Jekyll site repository on GitHub as the starting template for your Jekyll site, fork and clone the Jekyll site repository on GitHub to your local computer. For more information, see "Fork a repo."

Note: As of Jekyll 3.2, the default Jekyll site contains a Gemfile that locks Jekyll to the Gem version you build it with. To instead lock it to the version used by GitHub Pages, you'll uncomment the gem "github-pages", group: :jekyll_plugins line in the steps below.

If you don't already have a Jekyll site on your local computer, create a Jekyll template site in a new directory:

To edit the Jekyll template site, open your new Jekyll site files in a text editor. Make your changes and save them in the text editor. You can preview these changes locally on your computer without committing your changes using Git by running a Jekyll command to build your site.

Preview your local Jekyll site in your web browser at http://localhost:4000.

Keeping your site up to date with the GitHub Pages gem

Jekyll is an active open source project and is updated frequently. As the GitHub Pages server is updated, the software on your computer may become out of date, resulting in your site appearing different locally from how it looks when published on GitHub.

Open TerminalTerminalGit Bash.

Run this update command:

If you followed our setup recommendations and installed Bundler, run bundle update github-pages or simply bundle update and all your gems will update to the latest versions.