What is Jekyll

Jekyll is an easy to use, “blog-aware static site generator.” What this means practically is that once you set up your blog the way you like it, submitting new blog posts is as easy as writing a plain-text document in Markdown and popping it into a _posts folder. Jekyll will parse all of the plain-text files and generate your blog, ready for publication. Writing a new entry is as easy as this:

---
layout: post
title: My first Jekyll post
date: 2015-03-01 15:00
categories: [blogging, jekyll]
---
# My first Jekyll post
It's pretty easy to use Markdown:

* Once you get used to the syntax,
* it's a breeze to make lists!

And also to hyperlink to my favorite sites, like <https://lospi.net>.

Why bother?

It’s not for everyone, but there are some serious advantages to the Jekyll way:

You get to build your post in Markdown, meaning you have fine-grained control over how your page gets built without having to deal with clunky markup (like HTML). If you’re used to Github-flavored Markdown already, it should be fairly clear how powerful this feature is.
Your site is a full-blown static site, meaning you can CSS style to your heart’s content, add whizz-bang JS, and bump <span>s around all you’d like. Of course, you can just use one of the many, many available examples.
You can put your blog under source control. This makes it really, really easy to keep drafts and to backup your site. As we’ll see with Github Pages hosting, publishing your updates is as easy as git push.
You own every byte of your blog–rather than worrying about whether Wordpress will ever renege on their export API.

I’ve been experimenting with Jekyll for a few days now and decided to make the switch.

Configuring a Local Instance

It is imperative to get a local instance of Jekyll running. This will allow you to iterate between your plain-text blog and the rendered pages without having to push your changes remotely. You can follow these instructions to get it set up. Basically, you need three things:

Ruby (with header files for compiling extension modules) installed. If you are on Windows, I highly recommend using Chocolatey to install ruby2.devkit. On Ubuntu, try apt-get install ruby-dev.
Bundler, which makes installations of Ruby gems much simpler. Installing Bundler should be as easy as gem install bundler.
Jekyll, which can either be installed with gem install jekyll or as part of a bundler install command.

Working off a template

You can browse the many, many available examples on Jekyll Sites, or work off the most current version of lospi.net. Note: you must sign up for a Github account.

Navigate to the parent directory you’d like to check the blog out into, and checkout one of the blogs, e.g. with the command:

git clone git@github.com:JLospinoso/jlospinoso.github.io.git

You can now navigate into the site’s folder, e.g. jlospinoso.github.io.git, and start a local webserver:

cd jlospinoso.github.io.git
bundle exec jekyll serve

Fire up your favorite web browser and navigate to https://127.0.0.1:4000/.

You can inspect the contents of the cloned repository to get an idea of how Jekyll generates content. The finished product is contained in the _sites folder (and should not be manually edited). Check out Jekyll documentation for an exhaustive list of the powerful things you can do–but here are a few items to get you started:

Try creating a new blog post. Navigate to the _posts directory and create a new file (following the date-title format of the other posts). Use the template shown earlier in this post, copy the format of one of the other files in _posts, or experiment on your own!
Look through _layouts to get an idea of how Jekyll converts the posts into fully marked-up HTML. Edit the default.html so that the site matches your name, site URL, etc.
Edit the css/screen.css file to give the site a new look.

Migrating from another sites

If you have a blog hosted on one of the common sites, JekyllImport can be used to turn their export dump into Markdown files that you can insert directly into _posts. I did this for Wordpress (.com), and the process was fairly painless. It will take a bit of manual manipulation to reverse the HTML back into Markdown if you want to make the posts match the new ones, though.

Hosting with Github

Now that you’ve got a local Jekyll-generated site, you’ll want to make it available to the public. It’s easy and free to do this with Github Pages. You’ve already signed up for an account earlier, so just follow the instructions here.

Login to Github and create your repository with username.github.io where username is, you guessed it, your username. Pull down your repository:

git clone https://github.com/username/username.github.io

You can now transfer all the files from the template you cloned earlier into your personalized github.io project. If you’re not too familiar with git, this should get you started:

git add --all
git commit -m "initial"
git push -u origin master

Navigate a browser to https://username.github.io/ and marvel at how easy it is to fire off a new blog post!

Jekyll via Github