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 jekyllThis 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 serveThe 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.MARKUPYEAR 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,descriptiongithubandauthorto your personal details. - Change
urltoyour_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 LalwaniVikas 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.
