Erik Yuzwa

Fullstack web developer with a touch of PC game development for good measure

3 August 2021

Creating your own free Jekyll website on Github Pages

by erikyuzwa

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.


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.

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!

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 -%}

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!

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.

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](

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.


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

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!