Set Up a Jekyll Blog in 5 Minutes with PooleBy Vikas Lalwani
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.
First you need to install Jekyll on your system. For Mac, run the following command in terminal to install Jekyll:
$ gem install jekyll
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.
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
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
hyde-master repository you just downloaded contains many folders like
_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.)
jekyll serve again in your terminal and you'll find the new post in your blog if you open
To ensure proper building of your blog, Jekyll requires this naming convention:
YEAR is a four-digit number,
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
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:
authorto your personal details.
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.
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.
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.