Getting started with GitHub Pages: Part 2 -- Using an official GitHub Pages theme

GitHub Pages is GitHub’s static site publishing platform. In addition to supporting regular HTML content, GitHub Pages is deeply integrated with Jekyll, a popular static site generator designed for blogging and software documentation. And that’s not all! GitHub Pages sites are used for everything from blogs to full blown sites.

In this guide, we’ll walk you through adding one of GitHub’s offical themes to the GitHub Pages site we began working on in the last part of this seriesIf you haven’t yet completed the steps in the previous guide, you’ll want to do that before we begin.

Step one: Create an file

In our last guide, we published your file as the main page of your site. This works, but isn’t ideal moving forward.

The reason for this is that GitHub Pages looks for either an index.html or file to use as the main page of your site. If it can’t find those, it will resort to using your repository’s file, but ocassionally this can cause your site to build in ways you don’t expect it to. Additionally, your file also serves as the front page of your repository, and because of that you may want to use your differently than you use the front page of your site. In our experience, it’s almost always a good idea to work with a dedicated or index.html file whenever possible.

With that in mind, we’re going to start by creating a new file named

If you don’t yet have content that you’d like to publish, you can add the contents of this Gist to serve as a placeholder while you’re working through the rest of this guide. It’ll give you a pretty good demonstration of what you can do with GitHub Flavored Markdown on GitHub Pages.

Step two: Pick the Cayman theme using the theme chooser

We’ve created our main page and added our content. Now we need to configure our site to use a theme.

GitHub Pages uses Jekyll to build and publish Pages sites by default, and Jekyll uses a configuration file named _config.yml to configure global settings your site. This means that, for themes that GitHub has designed, all you’ll need to do to add a theme to your site is add the right key and value to a _config.yml file in the root of your repository.

Rather than creating that file manually, we’ll be using the Jekyll theme chooser. Follow steps 2 through 5 in this GitHub Help article to select the Cayman theme with the Jekyll theme chooser and add it to your repository. This will create the _config.ymlfile and add the appropriate configuration values to it for us.

Step three: Add Jekyll front matter to

The last step is to add front matter to your file so that your Pages site publishes it with the appropriate theme. Front matter is a block of YAML at the very top of your published site’s files that tells Jekyll to treat the file as a special. You can set predefined variables (like the layout you want to use for that particular page) or even create custom ones of your own.

In this particular case, we’re going to add front matter to your file to set the layout for that page. To do this, first you’ll need to open the file in GitHub’s file editor.

Now that the file is open in the editor, you’ll add the following lines to the top of your file (before your page’s content):

layout: default

These three lines tell Jekyll where your front matter begins and ends (the three dashes at the top and bottom of your front matter), and tells Jekyll that you’d like to use the default.html layout file for this page.

Once you’ve added your front matter to the file, you’ll need to write a commit message in the “Commit changes” box below the file editor. Writing effective commit messages is a subject worthy of its own guide, but an example of a good message you could use for this commit is:

Add Jekyll front matter to

If you feel that your commit message needs more context or have any notes about the change you’re making, you can optionally add an extended description in the box below your commit message.

Once you’ve added your commit message and selected “Commit directly to the master branch”, you’ll submit your changes by clicking the green “Commit changes” button.

Step four: You’re done!

Once you’ve committed your changes, GitHub Pages will automatically build your site. It may take a couple of minutes, but you should now be able to see your the Cayman theme applied to your GitHub Pages site. If everything went well, it’ll look something like the image below:

Published site with Theme applied


]( & next steps

Congrats! You’ve just added a theme to your GitHub Pages site! Be on the lookout for the next part in the series where we’ll talk about setting up your GitHub Pages site locally, and please drop a comment below about any topics you’d like us to cover in the future.

Finally, as in my last article, I’ve provided some resources that might help you level up your GitHub Pages skills.