In addition to supporting regular HTML content, GitHub Pages support Jekyll, a simple, blog-aware static site generator. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers some other advanced templating features.

Using Jekyll

Every GitHub Page is run through Jekyll when you push content to a specially named branch within your repository. For User Pages, use the master branch in your username.github.io repository. For Project Pages, use the gh-pages branch in your project's repository. Because a normal HTML site is also a valid Jekyll site, you don't have to do anything special to keep your standard HTML files unchanged. Jekyll has thorough documentation that covers its features and usage. Simply start committing Jekyll formatted files and you'll be using Jekyll in no time.

Installing Jekyll

We highly recommend installing Jekyll on your computer to preview your site and help diagnose troubled builds before publishing your site on GitHub Pages.

Luckily, installing Jekyll on your computer, and ensuring your computer most closely matches the GitHub Pages settings is easy, thanks to the GitHub Pages Gem and our dependency versions page. To install Jekyll, you'll need a few things:

  1. Ruby - Jekyll requires the Ruby language. If you have a Mac, you've most likely already got Ruby. If you open up the Terminal application, and run the command ruby --version you can confirm this. Your Ruby version should begin with 1.9.3 or 2.0.0. If you've got that, you're all set. Skip to step #2. Otherwise, follow these instructions to install Ruby.

  2. Bundler - Bundler is a package manager that makes versioning Ruby software like Jekyll a heck of a lot easier if you're going to be building GitHub Pages sites locally. If you don't already have Bundler installed, you can install it by running the command gem install bundler.

  3. Jekyll - The main event. You'll want to create a file in your site's repository called Gemfile and add the line gem 'github-pages'. After that, simply run the command, bundle install and you're good to go. If you decided to skip step #2, you can still install Jekyll with the command gem install github-pages, but you may run into trouble down the line. Here’s an example of a Gemfile you can use (placed in the root directory of your repository):

source 'https://rubygems.org'
gem 'github-pages'

Running Jekyll

To run Jekyll in a way that matches the GitHub Pages build server, run Jekyll with Bundler. Use the command bundle exec jekyll serve in the root of your repository (after switching to the gh-pages branch for project repositories), and your site should be available at http://localhost:4000. For a full list of Jekyll commands, see the Jekyll documentation.

Keeping Jekyll up to date

Jekyll's 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. To keep Jekyll up to date, you can run the command bundle update (or if you opted out of step 2, run gem update github-pages).

Configuring Jekyll

You can configure most Jekyll settings by creating a _config.yml file.

Defaults

We set the following defaults, which you are free to override in your _config.yml file:

pygments: true
github: [Repository metadata]

For the content of the repository metadata object, see repository metadata on GitHub Pages.

Configuration Overrides

We override the following _config.yml values, which you are unable to configure:

safe: true
lsi: false
source: your top-level directory

Keep in mind that if you change the source setting, your pages may not build correctly. GitHub Pages only considers source files in the top-level directory of a repository.

Troubleshooting

If your Jekyll site is not rendering properly after you push it to GitHub, it's useful to run Jekyll locally so you can see any parsing errors. In order to do this, you'll want to use the same versions of Jekyll and other dependencies that we use.

To ensure your local development environment is using the same version of Jekyll and its dependencies as GitHub Pages, you can periodically run the command gem update github-pages (or bundle update github-pages if using Bundler) once Jekyll is installed. For more information, see the GitHub Pages Gem repository.

If your page isn't building after you push to GitHub see the Pages don't build article.

If you are having issues with your GitHub Jekyll Pages, make sure you are not using categories that are named the same as another project, as this could cause path conflicts. For example: if you have a blog post named 'resume' in your User Page repository and a project named 'resume' with a gh-pages branch, they will conflict with each other.

Turning Jekyll off

You can completely opt out of Jekyll processing by creating a file named .nojekyll in the root of your Page repository and pushing that file to GitHub. This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special directories and does not copy them to the final destination.

Contributing

If there's a feature you wish that Jekyll had, feel free to fork it and send a pull request. We're happy to accept user contributions.