Set Up a Jekyll Blog in 5 Minutes with Poole

Key Takeaways

• Jekyll, a static site generator written in Ruby, can be used to create simple, manageable websites or blogs without the need for complex databases. It can be hosted for free on GitHub Pages.
• Poole, described as a “foundational setup” for Jekyll sites, can be used to streamline the process of setting up a Jekyll site. It comes with example templates, pages, posts, and styles to get started quickly.
• Adding new posts to a Jekyll blog involves placing a Markdown file in the _posts folder and ensuring it contains the appropriate YAML front matter at the top. The blog can then be published via GitHub Pages, which requires a basic understanding of Git.

In recent times, there has been something of a swing away from complex, database-driven websites, back towards simpler, more static sites—where feasible, of course, such as with a simple portfolio site or blog.

This isn’t to say that people are returning to the .html sites of yesteryear, though. You still want to be able to manage templates and site-wide code efficiently, and that’s where static site generators come in.

Static site generators are designed to take your various static files and turn them into a website. There are lots and lots of them to choose from, and there are recent articles about them here on SitePoint, covering the different languages they come in, Node-based options, their potential advantages over WordPress, and even how to roll your own with Grunt.

In this article, we’ll look at Jekyll, one of the most popular and widely used. I’ll describe how you can build a blog, with minimal coding, and then host it for free on GitHub Pages. We’ll also make use of Poole, a kind of framework—or “foundational setup”—for building Jekyll sites.

Jekyll in a Nutshell

Jekyll is written in Ruby. It’s installed on your computer as a Ruby gem. It’s not a CMS, it’s not blogging software, it doesn’t come with templates, content and so on. It’s much simpler than that. Think of it as a simple program that provides handy ways to process your files.

Once Jekyll is installed, you can put it to work from the command line. It can do things like process Markdown, and because it generates a static site, you can easily view progress locally, and host your site on a static web server like GitHub Pages.

Installing Jekyll

First you need to install Jekyll on your system. For Mac, run the following command in terminal to install Jekyll:

$ gem install jekyll

This will automatically install all of Jekyll’s gem dependencies. If you get stuck during installation, check out the troubleshooting page on Jekyll’s official website or file an issue on GitHub.

While Jekyll is not officially supported on Windows, you can still run it with some tweaks. Please refer to Jekyll on Windows page on Jekyll website or to this guide by Julian Thilo.

Getting Poole and Your First Server

Instead of starting with a raw Jekyll theme, let’s use Poole. It was created by Mark Otto, and this is how he describes it:

Poole is the butler for Jekyll, the static site generator. It’s designed and developed by @mdo to provide a clear and concise foundational setup for any Jekyll site. It does so by furnishing a full vanilla Jekyll install with example templates, pages, posts, and styles.

You can see the basic version here. Although it’s very good for a minimal blog, I like the two themes built on top of it more: Hyde and Lanyon. Let’s use Hyde for building our demo blog.

To get the setup for Hyde, go to its GitHub page and download the repository. Place it into the folder of your choice and head over to the terminal. Let’s assume you keep it on your Desktop. Run following commands to move to that directory and start the server:

$ cd Desktop/hyde-master/

$ jekyll serve

The jekyll serve command will start a development server that will allow you to preview the generated site in your browser locally.

To understand what I mean, open a new tab in your browser and type: http://localhost:4000. If you’ve followed everything properly you’ll find your newly born blog there.

Adding New Posts

The hyde-master repository you just downloaded contains many folders like _layouts, _posts and _includes. But there’s just one folder you need to care about if you want to manage posts for your blog: _posts. It contains all your posts in Markdown format.

For adding a new blog post, simply place your Markdown file in the _posts folder. Make sure your Markdown files contain the following (known as YAML front matter) at the top:

---
layout: post
title: Your Post Title
---

This will tell Jekyll that you’re adding a post. (Check the sample posts in the _posts folder if you have any doubts.)

Run jekyll serve again in your terminal and you’ll find the new post in your blog if you open http://localhost:4000.

To ensure proper building of your blog, Jekyll requires this naming convention:

YEAR-MONTH-DAY-title.MARKUP

YEAR is a four-digit number, MONTH and DAY are both two-digit numbers, and MARKUP is the file extension representing the format used in the file (in our case md). For example, your first post can be named 2015-03-29-my-first-post.md.

Publishing Your Blog

Once you’ve followed the steps above, and have added some of your own posts, you are ready to show your new blog to the world. You can post your files to many web hosts, but GitHub has made it very easy (and free!) to host a static Jekyll site via GitHub Pages. All you need to have is a GitHub account.

Before pushing it to GitHub, let’s make some changes:

In config.yml file:

• Change title, tagline, description github and author to your personal details.
• Change url to your_github_username.github.io.

In CNAME, mention your_github_username.github.io instead of hyde.getpoole.com. And edit about.md to include your details.

One you’ve made above changes, create a repository your_github_username.github.io and move all the files from your desktop to that repository.

Try opening your_github_username.github.io in a browser, and you’ll find your new blog there.

An important point to note: you’ll need to know a little bit of Git to be able to add your new posts to the repository. If the command line isn’t your thing, there are lots of tools—such as GitHub for Mac—that make it easy to work with Git. Either way, once you’ve added your posts to the repository, GitHub Pages will take care of the rest.

Further Reading

This post was about getting you started with Jekyll, but there’s a lot that you can do if you are willing to spend some time to learn. You’ll find following resources useful for understanding Jekyll and Git a little better:

• Jekyll Documentation—very neat and to the point documentation
• Intro to Jekyll—a good explanation by Johan Ronsee
• Basics of Git and GitHub—from the official GitHub YouTube channel
• Learn Git Basics in 15 mins—an interactive tutorial by Code School.

I hope you found this article useful. If you are trying to build a blog using the steps mentioned above and get stuck anywhere, please ask a question in the comments below. I’ll be active there.

Frequently Asked Questions (FAQs) about Setting Up a Jekyll Blog in 5 Minutes with Poole