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 series. If you haven't yet completed the steps in the previous guide, you'll want to do that before we begin.
In our last guide, we published your
README.md 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.md file to use as the main page of your site. If it can't find those, it will resort to using your repository's
README.md file, but ocassionally this can cause your site to build in ways you don't expect it to. Additionally, your
README.md file also serves as the front page of your repository, and because of that you may want to use your
README.md 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
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.
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.
The last step is to add front matter to your
index.md 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
index.md file to set the layout for that page. To do this, first you'll need to open the
index.md 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
index.md 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 index.md
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.
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:
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.