About

Projects

Blog

Contact

Jekyll From Scratch - Getting Started

16 Jul 2013 15 min. read Comments

Jekyll + GitHub Pages is the web platform underlying the new and improved
PixelCog.com. Ive decided to document my experience with it as I go along,
consolidating best practices, tips, and tricks into a helpful guide to use for my own
reference and the benefit of anyone else out there who might learn from my experience.

Table of Contents

Blogging for Hackers

Intro to Jekyll and GitHub Pages

Finding Good Information

Getting Started
Writing Your First Blog Post
Rendering Engine Basics
Liquid Template Engine

Publishing Your Site with GitHub Pages

Enabling a Custom Domain
Other Deployment Options
Migrating an Existing Blog
Helpful Resources
Final Thoughts

Blogging for Hackers

Although this is my first serious foray into blogging, Ive had some experience with a few
platforms in the past including Blogger, Tumblr, and WordPress. Ive also used the latter
as a content management system for some clients in past projects. They have generally
gotten the job done, but when it came time to implement PixelCog.com, my occasional
frustrations with them have driven me to experiment with some new options.
Being a professional web developer, I decidedly dont want a solution which sacrifices
flexability so that it can hold my hand through things I can handle myself. I wanted a
completely hackable blog platform. As I set out to do some research, I had a few criteria
in mind:
Automation I dont want to create everything from scratch. I need a platform
that will allow me to provide the common trappings of a modern blog (rss,
pagination, tagging, content management, etc.) without a ton of effort.
Control/Portability I want to have full control over the source material. I dont
want to publish it just to have it exist in some content silo where I cannot easily
export it. Version control is a huge plus too.
Staying Power I dont want to build a website on top of some new flashy
platform with no established community, nor do I want to use a free venturefunded blog service with an unknown monitization strategy.
Text Formatting I have been using Markdown for years and it is far and away
the best markup language to manage hypertext content in a natural, readable,
portable way. I dont want to be forced into a choice between spaghetti code
generating WYSIWYG editors, overly simplistic BBCode, or manual HTML.
Customization I want every bit of HTML, JavaScript, and CSS sent to the
browser to be under my control, and I want a robust templating system to make
managing it painless.
Simplicity/Scale If self-hosting I dont want unneccesary database overhead or
legacy one-size-fits-all code impeding my ability to maintain a simple, scalable
hosting solution.
Security If self-hosting I dont want to become a server maintenance expert to
run a simple website. I am competent enough to do it, but I also know that to do it
well can be a full time job, and I wear enough hats in my job already.
Given these criteria I set out to look at a few solutions. The first one I landed on was
Scriptogr.am. At first glance it seemed like it would fit quite well. It takes Markdown files

hosted in a Dropbox folder, compiles them using a simple customized template, and
hosts them for you for free. My main reservations were the absense of a monitization
strategy (theres no such thing as a free lunch), a few unfavorable anecdotes from
switchers, and an apparant lack of active development (as of this writing, the last
development blog update was 10 months ago in Sept 2012). Scriptogr.am has some
promise, but Id rather give it a few years to incubate and see where it ends up.
A little later I heard about an open-source project called Octopress from the folks on the
/dev/hell podcast and it appeared to represent nearly everything I was looking for;
Markdown support, incredibly easy self-hosting, and extreme flexibility while still
providing a solid framework with which to build my website. Perfect!

Deciding to give it a try I dug deeper and learned that Octopress is actually a
bootstrapped layer on top of another project called Jekyll. Having heard this I decided to
give vanilla Jekyll a try before dealing with any (potentially unnecessary) layer of
abstraction provided by Octopress.

Intro to Jekyll and GitHub Pages

Jekyll is a powerful static website generator. It takes raw markup files and templates and
compiles them into a complete, static html website. Since it requires no server-side
scripting components it can be hosted on bare bones file servers like Amazon S3 rather
than elaborate server stacks with a scripting language like PHP tied to a SQL database
where you need to worry about things like security and scalability.
Jekyll happens to be the engine behind GitHub Pages which is easily Jekylls most
attractive hosting solution. With it you can simply upload your Jekyll blog to a GitHub
repository and have it automatically compiled and deployed through a post-receive hook
each time you commit. Through this setup, publishing your blog to GitHub becomes as
simple as typing git push ! The service is free, has unlimited-bandwidth (AFAIK), and
allows custom domains, and since I already use git for all of my professional projects, this
workflow felt right at home.
The one catch to using GitHub Pages is its lack of plugin support. For obvious reasons,
GitHub doesnt want people executing arbitrary ruby code on their servers, so Jekyll is
run in safe mode. This can be worked around by adding an extra build-step prior to
publishing or by automating deployment with rake files, commit hooks, or shell scripts,
but I have chosen to forgo plugins and go the simple route for a few reasons:

1. Using a vanilla Jekyll deployment is more portable, simple, and elegant. Im not a
fan of unnecessary complexity.
2. GitHub Pages default deployment solution requires no additional setup. I could go
to any computer, clone my repo, make some changes, and push without mucking
around with commit hooks, installing dependencies, and so forth.
3. Most anything youd want to do with your blog can be done without plugins.
I have decided to keep my blog completely plugin free and GitHub Pages compatable,
utilizing only Liquid, Markdown, and core Jekyll functions. If youd like to work with
plugins I wont be covering any of that here, but there are many other resources out
there to help you get past those logistical hurdles.

Finding Good Information

Jekyll may be rising in popularity, but its community is still quite small, and Google is not
yet good at curating its more helpful online resources. Jekylls own official website and
docs rank below other search results on several Google queries. The project site could
certainly use some good link juice from blog posts like this and others.
The project recently reached maturity with its 1.0.0 release (May 2013), bringing with it
support for drafts, excerpts, and many other enhancements. Many Jekyll guides and
resources, inlcluding popular child projects Octopress and Jekyll-Bootstrap, still
disseminate obsolete solutions aimed at patching-in some of these enhancements
through plugins. This blog post is largely a reaction to the lack of post-1.0, non-plugindependent resources out there for new Jekyll users.
I suspect many of the remaining plugin-based workarounds will also be made obsolete as
popular features continue to get rolled into core. Tag and category pagination, more
robust templating features, and Octopress-like publishing workflow automation arent
far down the pipeline.

Getting Started

Getting your feet wet with Jekyll is very simple. I find it best to force installation of the
same versions of Jekyll and Liquid currently used on GitHub Pages to ensure feature
parity (1.0.3 and 2.5.0 respectively as of July 2013)(2.2.0 and 2.6.1 as of August 2014).
Assuming you already have ruby installed, following Jekylls Quick-Start Guide is as
simple as this:

$ gem update --system

$ gem install liquid -v 2.6.1
$
$
$
$

gem install jekyll -v 2.2.0

jekyll new blog
cd blog
jekyll serve -w

Now simply go to localhost:4000 and marvel at your creation

( crtl+c when youre done)

Update Nov 22nd, 2013: GitHub Pages now has its own gemfile to install the currently
used versions of Jekyll and its dependencies. You can now run gem install github-pages
in place of the above install commands. More information here.
Update Aug 21st, 2014: Fixed Jekyll and Liquid versions.

Writing Your First Blog Post

Looking at the shell directory structure that we just created youll notice a _posts

subdirectory. This is where your published blog posts will live. These must all follow the
naming convention YYYY-MM-DD-name-of-post.ext . The example post uses the extension
*.markdown but I much prefer the sussinct *.md extension; it makes no difference
either way. Jekyll will infer the date and permalink slug of your post from this name
unless overridden in the YAML front-matter (the content between the lines with three
dashes at the start of the file):
--layout: post
title: "Welcome to Jekyll!"
date:
2013-05-24 18:34:38
categories: jekyll update
--You'll find this post [...]

Beginning with the recent release of Jekyll 1.0, we can now create and preview blog post
drafts without mixing them in with published posts and conforming to this rigid file
naming convention. Simply create a _drafts folder in the root directory of your blog
and add a new file to it. Lets call it hello-world.md :

--layout: post
---

# Hello World
This is my first _ever_ Jekyll post!

Save the file and run Jekyll with the --drafts flag to preview your work.
$ jekyll serve -w --drafts

Go back to localhost:4000 and you should see your new post listed under todays date.
Jekyll infers the post title from the filename if none is provided, and uses the files lastmodified date as the publication date.
Now when youve finished a draft and decide to publish it, the process is pretty straight
forward. Move the file from _drafts to _posts , add the year formatted as YYYY-MM-DDto the start of the filename. You may then wish to configure the front-matter to add
meta-data like tags, categories, permalink, et cetera.
Pro Tip I like to store my blog post drafts where I can view and edit them on the go. To
do this, I made my _drafts folder a symbolic link to a folder in my Dropbox. Using this
method I can access my drafts from Byword on my iOS devices and update them from
anywhere.

Rendering Engine Basics

Files in _posts are rendered according to the default permalink rule

( /:categories/:year/:month/:day/:title.html ) which can be overridden in
_config.yml or the posts own front-matter (like permalink: /foo/bar/ ).
Page templates are assigned with the layout front-matter variable and can be found in
the _layouts directory. Jekyll provides two by default, default.html and post.html .
Template include files are found in _includes and can be embedded with {% include
file.ext %} .
All other files follow these four rules:

1. Files and directories which begin with . or _ are ignored.

(unless overridden in _config.yml )
2. Files without YAML front-matter are passed through when rendered.
( /css/style.css or /foo.html with no front-matter are copied verbatim)
3. Files with YAML front-matter are processed with Liquid and (if appropriate)
rendered in Markdown with an appropriate file extension change.
( /file.md with front-matter becomes /file.html )

4. Files with YAML front-matter which specify a permalink are preprocessed and
rendered at the given url. If the permalink is a directory, index.html is used.
( permalink: /fancy/link/ yields /fancy/link/index.html )
Once you understand these simple rules, youll have a pretty firm grasp of Jekylls
rendering engine.

Liquid Template Engine

Going over the intricacies of the Liquid templating language is beyond the scope of this
tutorial, but there are some good references here and here. Anyone who has used a
basic templating language before will find all the usual trappings for loops, if/else logic,
variable assignment, etc. Id encourage you to play around with it and explore the official
Jekyll documentation before proceeding with the more advanced stuff in my next posts.

Publishing Your Site with GitHub Pages

Once youve edited your first post and played around with the templates, youll want to
publish your work. Provided you already have git installed, this is a pretty simple process.
Following the instructions on help.github.com, youll need to create an empty repository
named {user or org name}.github.io and then perform the following actions:
$
$
$
$

git
git
git
git

init
add -A && git commit -m "initial commit"
remote add origin git@github.com:username/username.github.io.git
push -u origin master

* remember to replace username with your user or org name

Within 10 minutes (but usualy much quicker) your Jekyll blog will be rendered and
online!

Enabling a Custom Domain

If you want to enable a custom domain name on GitHub Pages, you can perform the
following steps (also from help.github.com):
Go to wherever youre domains DNS zone is hosted and edit your A record to point to
204.232.175.78 .
Add a CNAME file to the github repo to tell it to use our domain:
$ echo "mydomain.com" >> CNAME

$ git add -A && git commit -m "enable custom domain"

$ git push

* replace mydomain.com with your domain name

Wait for the DNS zone changes to propogate (up to 48 hours, but usually much sooner),
and enjoy!

Other Deployment Options

GitHub Pages may be my deployment option of choice, but it certainly isnt the only
option. As mentioned before, Amazon S3 is another good, low-cost solution. This and
many other options and deployment automation techniques can be found on Jekylls
official website.

Migrating an Existing Blog

Jekyll has built support for importing blog data from a large number of blogging
platforms including Tumblr, WordPress, Blogger, and many others. Visit Jekylls
migration page for more info.
In my next post, Ill cover ways to maintain urls you were using from your old blog so you
dont break all of your inbound links.

Helpful Resources

Jekyll Official Documentation

Jekyll Changelog
Jekyll Template Reference
Liquid Engine Reference
Liquid Filters Reference

Markdown Reference
GitHub Pages Help Section
Development Seeds Jekyll Blog really helped me understand the basics of
Jekylls rendering engine when I started out, and provides some really clever
examples of what you can do with Jekyll.
Sebastian Teumerts Jekyll Template Toolkit an indispensable plugin-free Jekyll
resource.
Tobias Sjstens Blog has some nice tips and tricks for Jekyll, also plugin-free.
StackOverflows Jekyll Tag the place to go to ask questions if you get hung up.

Final Thoughts

One of the biggest boons for budding young web developers in the last few decades has
been the ability to hit view source to instantly see whats behind the curtain of their
favorite website. For a kid who begged his parents for triangle shaped screwdrivers so
that he could dissect his McDonalds toys and put them back together, I found this
feature invaluable when I first cut my teeth on HTML in my early teens. Its always easier
to learn by observing real-life examples.
This is one reason why Jekylls pairing with GitHub Pages is so awesome. Many of the
Jekyll websites out there are hosted on public GitHub repositories, free to anyone who
wants to dissect them and see what makes them tick. You can view the source material
for this post, and even this entire website on GitHub. One of the best ways Ive found to
learn it is to find a Jekyll blog you like and take a look at how they do things.
Go forth and start blogging like a hacker!
In my next post Ill be covering some more advanced website structural configuration
with Jekyll.

PixelCog is the home of Mike Greiling, freelance programmer,

consultant, and entrepeneur.
github | twitter | facebook
2015 PixelCog Inc.

Made with Jekyll Theme by orderedlist