You can add a Jekyll theme to your GitHub Pages site by editing your site's _config.yml file.

Jekyll themes allow you to install a different design for your GitHub Pages site without editing or copying CSS files. Jekyll themes package the files you need to change your site design, including files stored in your assets folder, such as SCSS, SASS, images, CoffeeScript.

Note: Not all Jekyll themes are supported. For a list of Jekyll themes that are supported by GitHub Pages, see https://pages.github.com/themes.

You can override a Jekyll theme's defaults with your site's content in these folders:

  • _layouts
  • _includes
  • _sass
  • assets

For more information about the Jekyll theme files you can override, see your theme's README or other documentation in your theme's source repository.

Once your Jekyll theme has been added in your site's _config.yml file, and assuming the theme is supported by GitHub Pages, your site will build with the requested theme.

Adding a Jekyll theme to your site

Adding your theme in your site's _config.yml file on GitHub

  1. On GitHub, navigate to the main page of the repository.

  2. In your repository, browse to _config.yml.

  3. In the upper-right corner of the file view, click to open the file editor. open file editor with edit icon
  4. Activate the theme by adding a new line to your _config.yml with the theme name: add-theme-to-config-file
  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. Commit message for your change

  6. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is master, you should choose to create a new branch for your commit and then create a pull request. Commit branch options

  7. Click Propose file change. Propose file change button

  8. If you created a pull request, merge your pull request into your GitHub Pages publishing branch, which is usually master and sometimes gh-pages.

Your site should now publish with the new theme you added.

Previewing your Jekyll theme locally

If you haven't already, add your Jekyll theme to your site. You can preview the theme locally by following the steps detailed in the sections below.

Note: Before attempting to preview your Jekyll theme locally, ensure the following:

  • Have a local copy of your remote GitHub Pages site repository on your computer. If you don't have a local copy of your site repository, see "Cloning a repository." If you don't have a remote GitHub Pages site repository on GitHub yet you can use someone else's open source site repository as a starting template and fork it.
  • Have Bundler installed.

Adding your theme as a Gem to your Gemfile

Note: If you're using the web-only interface to edit, you don't need to add your theme to the site's Gemfile, if one exists.

  1. On GitHub, navigate to the main page of the repository.

  2. In your repository, browse to Gemfile.

  3. In the upper-right corner of the file view, click to open the file editor.
  4. Add a new line to your Gemfile with the theme name in quotations: add-theme-gem-to-gemfile-on-github

    Tip: You can add multiple Jekyll themes to your Gemfile but to activiate a theme, only one theme can be added to your _config.yml file.

  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. Commit message for your change

  6. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is master, you should choose to create a new branch for your commit and then create a pull request. Commit branch options

  7. Click Propose file change. Propose file change button

  8. If you created a pull request, merge your pull request into your GitHub Pages publishing branch, which is usually master and sometimes gh-pages. For more information on which branch to publish your site with, see "User, Organization, and Project Pages."

Installing your theme using Bundler

  1. Open TerminalTerminalGit Bash.

  2. Navigate into your local GitHub Pages site repository:

    cd my-pages-site-repository
    
  3. Load your changes from your remote site repository on GitHub to your local site repository:

    git pull
    

    Tip: For more information on using git pull, see "Fetching a remote."

  4. Install your Jekyll theme Gem using Bundler:

    bundle install
    Fetching gem metadata from https://rubygems.org/............
    Fetching version metadata from https://rubygems.org/...
    Fetching dependency metadata from https://rubygems.org/..
    Resolving dependencies...
    . . .
    Installing minima 1.0.1
    Using bundler 1.10.6
    Bundle complete! 2 Gemfile dependencies, 54 gems now installed.
    Use `bundle show [gemname]` to see where a bundled gem is installed.
    
  5. Push your changes up to your remote GitHub Pages site repository on GitHub, replacing master in the example below with gh-pages if you use a gh-pages branch to publish your site:

    git push origin master
    

Adding a Jekyll theme on the command line

  1. Open TerminalTerminalGit Bash.

  2. Navigate into your local site repository:

    cd my-pages-site-repository
    
  3. To add a theme to your site's Gemfile, open your favorite text editor, such as Atom, and add this line to your Gemfile using your selected theme's name in quotations:

    gem "minima"
    # Minima is a default theme for Jekyll sites.
    

    Tip: You can add multiple Jekyll themes to your Gemfile but only one of these themes can be added to your _config.yml file to activate your theme.

  4. Install your Jekyll theme Gem using Bundler:

    bundle install
    Fetching gem metadata from https://rubygems.org/............
    Fetching version metadata from https://rubygems.org/...
    Fetching dependency metadata from https://rubygems.org/..
    Resolving dependencies...
    . . .
    Installing minima 1.0.1
    Using bundler 1.10.6
    Bundle complete! 2 Gemfile dependencies, 54 gems now installed.
    Use `bundle show [gemname]` to see where a bundled gem is installed.
    
  5. To activate your theme, using your favorite text editor, add a new line to your site's _config.yml file with your theme's name:

    theme: minima
    
  6. Add and commit your changes using Git:

    git commit -a
    # Adds your changes
    git commit -m "added theme to Gemfile & _config.yml"
    # Commits your changes with a commit message
    
  7. Push your changes up to your remote GitHub Pages site repository, replacing master in the example below with gh-pages if you use a gh-pages branch to publish your site::

    git push origin master
    

Your site should now publish with the new theme you added.

Further reading