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
andauthor
to your personal details. - Change
url
toyour_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
What is Jekyll and why should I use it for my blog?
Jekyll is a simple, blog-aware, static site generator that’s perfect for personal, project, or organization sites. It takes a template directory containing raw text files in various formats, runs it through a converter and renderer, and spits out a complete, ready-to-publish static website. The main advantage of using Jekyll is its simplicity. It doesn’t require databases or updates, making it secure and easy to maintain. Plus, you can host your website directly on GitHub for free.
What is Poole and how does it complement Jekyll?
Poole is a foundational setup for Jekyll projects. It provides 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. This helps you get up and running with Jekyll in no time.
How do I install Jekyll and Poole?
To install Jekyll, you need to have Ruby installed on your system. Once you have Ruby, you can install Jekyll by running the command gem install jekyll bundler
. For Poole, you simply need to download or clone the Poole repository from GitHub and you’re good to go.
How do I create a new post in Jekyll?
Creating a new post in Jekyll is straightforward. You just need to add a file in the _posts
directory that follows the convention YYYY-MM-DD-name-of-post.ext
and Jekyll will automatically process it into a post.
How do I customize the look and feel of my Jekyll blog?
You can customize the look and feel of your Jekyll blog by editing the stylesheets and layout files in the _layouts
and _sass
directories. You can also add your own stylesheets in the css
directory.
How do I host my Jekyll blog on GitHub?
Hosting your Jekyll blog on GitHub is easy. You just need to create a new repository, push your Jekyll site to it, and then configure the repository settings to use the gh-pages
branch for GitHub Pages.
How do I update my Jekyll blog?
Updating your Jekyll blog is as simple as making changes to your files and pushing them to your GitHub repository. Jekyll will automatically rebuild your site whenever you push changes.
Can I use Jekyll with other languages?
Yes, Jekyll supports multiple languages. You can configure the language of your site in the _config.yml
file and Jekyll will handle the rest.
How do I add images to my Jekyll blog?
You can add images to your Jekyll blog by placing them in the images
directory and referencing them in your posts or pages using the appropriate Markdown or HTML syntax.
Can I use plugins with Jekyll?
Yes, Jekyll supports a wide range of plugins that can extend its functionality. You can install plugins by adding them to your Gemfile
and _config.yml
file, and then running the bundle install
command.
Vikas Lalwani is a front-end developer with an eye for design. He loves to play with HTML, CSS, and JavaScript to create tiny apps for fun. You can check out his experiments on his home page.