Getting started with GitHub Pages: Part 4 -- Customizing your Pages site

Customizing your Pages site

In part three of this series, we walked through setting up your GitHub Pages site locally with Jekyll. If you’ve followed along this far: congrats! You now have a themed and fully-functioning GitHub Pages site and the ability to work on it locally. Great! Let’s use our new found ability to work locally and customize our Pages site a bit.

In this continuation of the series, we’re going to:

  • Set our site up to be a blog
  • Customize our site’s header color
  • Write our first blog post

Before you get started

We’re going to be working on our Pages site locally, so this guide assumes that you already set a few things up on your own while following part three of this series. The specific prerequisites are as follows:

  1. You’ve completed the first three guides in this series (if not, here you go: Part onepart twopart three)
  2. You’ve installed Git
  3. You have a text editor (I recommend Atom)
  4. You’ve installed both Ruby and the Bundler gem
  5. (Optional) You’ve installed GitHub Desktop
  6. You know how to use [Jekyll commands to build your site locally


If you’ve completed the previous guides and have your Pages site running locally, then you’re ready to proceed.

Step zero: Download the example files

First we’re going to give you some template and placeholder files to download:

[Example files


Once they’ve downloaded to your computer, you’ll want to extract the files inside of the ZIP file into your local repository. Once you’ve done that, your local repository should look like this:

| - _layouts/
| | - blog.html
| | - default.html
| - assets/
| | - css/
| | | - style.scss
| - _config.yml
| - Gemfile
| - Gemfile.lock
| -

Step one: Set our site up to be a blog  

This is a bit different than what we’ve had you do before, so let me explain what we’ve had you add to your site.

Jekyll looks for the templates for your site in the \_layouts directory of your repository before it looks elsewhere. In part three of this series, we configured our Pages site to use the Cayman theme. Since we didn’t have a \_layouts directory in our site at that time, it used the default.html file in Cayman’s repository. Since we want to customize our Pages site’s HTML and CSS, we need to copy that default.html file into our repository and place it in the right folder. In addition to the default.html layout, you’ll notice that I also added a blog.html file to the \_layouts directory. This layout will show a list of every post in the \_posts directory that we’ll be creating later.

While creating Jekyll templates from scratch is outside of the scope of this guide, I would recommend reading the official Jekyll documentation about templating to understand exactly what’s going on in both layouts.

Finally, if you look at our documentation about customizing the CSS and HTML in your Jekyll theme, you’ll see that in order to edit the styles for our theme we need to create a style.scss file and place it in the assets/css/ directory.

Now that all of those files have added to our local repository, we want to make sure to commit them by running the following commands:

git add . git commit -m "Add a blog to my Pages site"

Once you’ve done that, you’re ready to proceed.

Step two: Customize the header

By default, Cayman gives us a blue-to-green page header, but a question we often get from users is “How do I change the color of that header?” To do that, we’ll first ensure that we’re importing all of the existing styles that the Cayman theme uses, and we’ll do that by adding the import statement below to our assets/css/style.scss file:


@import"{{ site.theme }}";

Below that, we’ll add a CSS rule that selects the .page-header class in our layout and overrides the existing style with a new linear gradient:


Done! Commit your changes like we did before:

git add . git commit -m “Change the page header colors”

Then preview your site locally:

bundle exec jekyll preview

And you’ll see a brand new violet-to-purple gradient in your Page’s site’s header.

Want to pick different colors than I did? You can replace the Hex color codes with your own choices. There are many tools on the web to help you pick your colors, but here’s one that we recommend:



Step three: Create your first post

Next, we’ll need to create the first post for our blog. To create a post, you’ll need to first create an empty directory in your local repository named \_posts. This directory will contain every blog post you want published on your site. Next, you’ll create a post by creating a new markdown file in that directory.

How you name files in this folder is important. Jekyll requires blog post files to be named according to the following format:


So in my case, I’ve named my file, but you can name your post whatever you’d like as long as it adheres to that format.

Step four: Hello world

Inside of your newly created post file, you’ll write your first blog post. To make things a bit easier for you, I’ve provided some dummy Markdown content for your first post below:

# Hello WorldThis is the first post on my\*\*blog\*\*. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\*quis nostrud exercitation ullamco laboris\*nisi ut aliquip ex ea commodo consequat.

Copy and paste the content above into your post file, save your changes, and then commit your new post using Git like we did before.

git add . git commit -m “Add Hello World post to my blog”

Now you can use Jekyll once more to preview your site and see your new blog:

bundle exec jekyll serve

You’re done!

That’s it! After you run the command to preview your site with Jekyll and open it in your browser, you’ll see your redesigned Pages site complete with a new blog section.

From here, you can customize your site’s theme a bit more, commit your changes, and then push the final redesign to GitHub for GitHub Pages to publish it.

Conclusion & next steps

Congratulations! You’ve just completed the Getting started with GitHub Pages series. From here, I would recommend taking a look at Jekyll’s official documentation to learn more about what you can do.

Finally, as always, I’ve provided some resources that will help you level up your GitHub Pages skills:


nice, this really helps 

I have so much trouble pulling request

@carrie3563 The Community Forum is a great place to get help if you’re having trouble with pull requests or anything else while using GitHub. I’d recommend opening a new topic in the appropriate Conversation Board so that other community members can better help you. Be sure to include details about the problem you’re having and what you have tried already. 

1 Like

The link in Step 0, gives not found when clicked on. Can someone help me with the files

1 Like

Where did the Step 0 placeholder files go?