GitHub Pages is certainly not a “new” product from GitHub. It was first launched sometime in 2008 as a service to GitHub users for hosting their project documentation or blogs.

When it comes to my own content, however, I always leaned towards self-hosting. For most of my technology choices in general, I see and have seen what happens when a business becomes reliant on a Walled Garden, or how little control over your own content you actually have.

That being said, there are enough positive aspects in my book, for deciding to give GitHub Pages an experimental try for my personal blog.

I’m excited to get started. Let’s take a look at moving your existing blog and/or starting a new Jekyll blog right on GitHub!

Step 1 - create a repository

Every single GitHub user has access to their own free GitHub Pages site. If you haven’t taken the time to create yours, or you want to give this a shot right now, then just create a new repository in your GitHub account.

  • Login to your GitHub account
  • Click the “New” button on your repositories page -
  • Name the new repository <githubusername> - so for example, mine is
  • Give it some kind of a description
  • Make sure the repository is set to Public so that the public internet can see it
  • For now, skip the optional checkboxes and hit the Create repository button


So far, so good.

Step 2 - setting up a Pages Theme

Now let’s setup a Pages theme to kickstart your content with. You can still modify and customize your site’s layout and CSS, but having a starting point can really help out.

  • From your new repository page, select the Settings
  • In the menu down the left side, choose Pages
  • By default, GitHub Pages will just monitor your main branch to trigger any rebuilds of your website. I suggest leaving this setting alone, but you have the option of changing it if you really feel its necessary.
  • In the Theme Chooser section, choose your site’s theme by clicking the Change theme button
  • Using the left and right navigation arrows, you can scroll between the various themes to start your website with. As you can tell, I went with the Hacker theme, but there’s some other cute ones.
  • Once you’re satisfied with your theme, hit the Select theme button
  • Github Pages will do its thing

With your theme chosen, you should now be able to view your site at https://<githubusername>

Step 3 - clone your repository

If you haven’t done so already, it’s time to clone your new repository so that you can start customizing your site and creating content!

  • git clone<githubusername>/<githubusername>
  • cd <githubusername>

Just a quick note that from now on, anytime you push changes up to your repository, GitHub Pages will trigger a Jekyll build of your website and attempt to publish it. So handy!

Step 4 - first update of your _config.yml

If you’re new to Jekyll, you might not be too familiar with the _config.yml file. This file contains the main configuration of your website. You can either open up this file (or any file) in your GitHub online editor, or with your text editor of choice on your local machine.

Let’s define some site basics:

title: <your new super cool website>         # displayed on your homepage
description: <some neat description>         # used in your theme as well as your website SEO
author: <your githubusername or first name>  # some themes make use of this

show_downloads: false                        # hide the "download this site" button

google_analytics: "UA-<blah>"                # most themes make use of your google analytics id

Commit and push your changes. A final reminder that once you push your changes up to GitHub, they’ll be live after a few moments.

Still using the default theme’s structure and layout, you should start seeing your website updated and reflecting the given values from your _config.yml.

Step 5 - add post pagination

By default, most themes (that I could see) didn’t account for any pagination of your content. In other words, once you start adding your existing posts from your blog or creating new ones, they’ll all just be showing up on your site’s homepage. Yuk!

Open up your _confg.yml again and add

# define pagination options
paginate: 5
paginate_path: "blog/page:num/"
permalink: blog/:title/

# plugins that your blog uses
  - jekyll-paginate

Now let’s tackle some reconfiguring of your blog’s homepage to take advantage of pagination.

Open up the index.html in your project root. You may have to go through some experimentation here, but the goal is to reference the paginator.posts hash instead of posts directly.

As an example, here’s the pagination code I’m using for my own site. Note the use of the paginator object hash here

{%- for post in paginator.posts -%}
        <span class="date">{{ | date: '%B %d, %Y' }}</span>
        <h3><a class="post-link" href="{{ site.baseurl }}{{ post.url }}">{{ post.title }}</a></h3>
        <p>{{ post.excerpt }}</p>
        {% if post.excerpt != post.content %}
            <a href="{{ site.baseurl }}{{ post.url }}">Read more</a>
        {% endif %}
{%- endfor -%}

  • The post.excerpt is the first few lines from your post content. By default, Jekyll uses the familiar <!--more--> markup to signal your specific excerpt content.
  • The if post.excerpt != post.content condition is testing if your post content is as long as your excerpt. If one is longer then the other, which is normally the case, then show a Read more link to take the reader to the full post.

step 6 - adding some post navigation

Now that some pagination has been setup on your homepage, let’s add some simple navigational elements. You can style these to heart’s content, but for now we’ll start with some simple markup.

Again, we’re editing the index.html in your project root

<!-- Pagination links -->
<div class="pagination">
    {%- if paginator.previous_page -%}
    <a href="{{ paginator.previous_page_path }}" class="previous button__outline">Newer Posts</a>
    {%- endif -%}
    {%- if paginator.next_page -%}
    <a href="{{ paginator.next_page_path }}" class="next button__outline">Older Posts</a>
    {%- endif -%}

Just cut and paste this code near the bottom of the file. Traditionally, it’s underneath the pagination code you added in Step 5, but you have total creative freedom to design whatever you want!

That’s it. Commit and push the changes.

step 7 - adding / migrating posts

Make sure a _posts folder is created in your project. If you’re new to Jekyll, this is the folder that will contain all your articles for your site!

  • Copy any existing or create new post files in this folder
  • You can call them whatever you wish, as long as their extension is .md or .markdown
  • Come up with your own naming standard. As an example, I typically use

Once you commit and push the changes, you should see your site now updated with the post content.

step 8 - create your own 404 page (optional)

It’s certainly not mandatory, but a fun exercise is to customize your site’s 404 page that is displayed to any visitor when they try and access a web page that either doesn’t exist or that they don’t have permissions to see.

To see what’s provided for you now, try https://<githubusername>

Provided you don’t ACTUALLY have a post with that name, you’ll see the default GitHub 404 page.

  • In your project root, create a new file,
  • Open it up in your favorite editor
  • Put in some Jekyll frontmatter and content

layout: default
permalink: /404.html

Uh-oh, we can't find the page you're looking for.

Here's some of my favorite sites
- [My Youtube Channel](
- [My Twitter](
- [My LinkedIn Profile](

  • Commit and push

Here’s where you can get creative. Maybe use the 404 page to advertise your best service, or your most popular blog post, etc. It’s your 404 page, go where the Spirit takes you.

step 9 - customizing CSS

In the last step of our migration, let’s add a way for us to customize our site content and styles. While the theme we’re using has its own CSS, we can certainly override it and provide our own.

  • In your project root, create an assets/css folder
  • Within the css folder, create a new file called style.scss
  • Open up this new file in your favorite editor, and make sure these lines are at the VERY TOP of the file


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

  • Close and save
  • Commit and push

Now you can start to define any CSS you wish. We’re using site.theme here in case you ever decide to switch to a different GitHub Pages theme. Handy!

I hope you found this guide, or parts of this guide, helpful for your own site migration. I have several other posts about Jekyll and GitHub Pages, so feel free to check those out!