Image via Wikipedia

Jekyll: Sites Made Simple:

Jekyll: Sites Made Simple

---

For the full text of this article go here

---

Just this last August, I decided to relaunch my web site; I chose to give WordPress the flick and try out Jekyll, a Ruby-based static site generator.

Jekyll at its core is a text transformation engine.

The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files.

Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout, and more.

This is all done through strictly editing files, and the web interface is the final product.

Jekyll is a blog-aware, static site generator.

It uses a set of template or layout files, the associated CSS files, and plain text files for the posts.

The posts can use the Markdown format or another similar markup language.

There's no content management system, no database, and no specific language support on the web server required---your site is a collection of plain old static HTML files.

Switching back to static markup may at first seem like a reversion to the late 1990s.

Yet Jekyll is a simple and elegant system that mimics the characteristics of a dynamic site---drawing content from a database and inserting it into templates via a CMS---without all that complexity.

As a firm believer in the KISS principle (Keep It Simple, Stupid), I always try to find the right tool for the job, and Jekyll is a simple solution to a common problem: "I want my own customized blog."

It's also flexible enough that it can easily be used for other tasks.

For example, GitHub uses it to drive GitHub Pages.

This article describes using Jekyll to build a web site: from downloading it, setting up a development environment, and hacking up template files.

I'll conclude with a word on maintaining updates between your development instance (for example, new blog entries) and synchronizing them to your web server.

Note that I've written this piece from a designer's perspective.

Although I had a number of technical hurdles to hop over, Jekyll remains rather simple; for instance, using Jekyll's template system and Liquid tags is easier than hacking a design as a WordPress theme.

Never fear, I intend this article to be as designer-friendly as possible.

Setting up a Jekyll blog is relatively smooth-going and boils down to a few straightforward steps.

Jekyll is written in Ruby, so you'll need to install it.

It's as simple as downloading the latest Ruby version for your platform and following the installation instructions.

The Ruby installation also includes the RubyGems packaging system, and allows you to download and install other Ruby libraries and programs.

If you're using Windows, choose the one-click installer, and make sure you tick the Enable RubyGems option when running the installer.

We'll be fetching Jekyll from the Gemcutter RubyGem hosting repository, but we first need to install the Gemcutter program.

The tumble command will simply make the RubyGems installer query the Gemcutter repository first, when downloading RubyGem packages.

This ensures that Jekyll is downloaded from the Gemcutter repository.

If you're on Windows you'll be entering the commands at the Windows command prompt (Start> Run...

Jekyll, like all good software, is modular and does one task very well, relying on other programs and libraries for additional functionality---after all, why reinvent the wheel?

This modularity also gives us choice: you can pick and choose from a variety of slightly different tools that perform similar tasks to extend Jekyll, depending on your preferences.

For example, if you'd rather write your blog posts in Textile instead of Markdown, you can.

For me, however, the default (Markdown) does the trick, and Gem only needs a small number of other dependencies, which are fetched automatically.

For a full list of available gems that extend Jekyll, see the list within the install instructions for Jekyll on GitHub.

Now with Jekyll installed let us set up the file system structure.

First, create a new directory---placing it within your user directory is fine.

That done we can execute Jekyll by issuing the jekyll command at the command prompt.

You'll notice that Jekyll creates a directory _site, which now holds an index.html file.

It's typically only a few lines long and allows you to avoid having to specify optional flags every time you run Jekyll from the command line; just stick them into _config.yml and Jekyll will use them every time it's run.

For more info on Jekyll configuration, see the configuration page on the Jekyll wiki.

When Jekyll is run, your posts are injected into the layouts using the Liquid tag: {{content}}.

Posts are plain text files that are named with the format $YEAR-$MONTH-$DATE-$TITLE.$FORMAT.

We'll create two templates for us to pick from: base.html, which is our base layout and post.html, which extends the base layout and is used for posts.

It was designed to allow designers and front-end developers to tweak their shopping interface without affecting the security on the server they're built on.

Apart from the specific directories and files mentioned above, all other directories and files are handled by Jekyll as expected and will be included in the generated site build in _sites/ when Jekyll is run.

Thus, a css/ and js/ directory and its contents, a favicon, and whatever else will all be added to the site build.

Jekyll comes with a simple web server that allows you to pop over to http://localhost:4000/ and view your site.

Even better, if you're actively updating and making changes, a useful flag to append to the jekyll command is --auto.

You can also add auto: true to the configuration file so that you can avoid having to type it in every time.

If you want to track your Jekyll files in a version control system, it's recommended to make an exception for the _site directory.

That's because the files in the _site directory are bound to change a lot, particularly during the development phase.

Deploying your generated static site is just a matter of copying the output in _site to your web server.

You could use FTP to upload your files, but there are a number of automated methods that make life easier, particularly when you just want to upload the new changes since the last upload.

My preferred current method is to use rsync, a little UNIX utility written by Canberra locals Andrew Tridgell and Paul Mackerras.

rsync synchronizes data from one location to another, and in doing so only sends changes rather than full files where possible.

There are a range of other, more complex automated methods, but they're beyond the scope of this article.

As a static site generator without any dynamic extensions means Jekyll has no comment support.

I've personally decided to avoid comments; besides avoiding having to deal with them at all (code-wise, styling-wise, spam-wise---yay!), the best feedback I've ever received were face-to-face or directly via email.

I also echo some of the sentiments raised by Alex Payne in his article, Why I Don't Allow Comments, and More on Everything Buckets in regards to fostering a higher quality discussion.

Despite blog CMSs as powerful as WordPress, Movable Type, and so on, I hope you can now see why it's worth reverting to a simplistic and rudimentary system like Jekyll: you use the right tool for the job.

Jekyll is a breeze to pick up; its learning curve is certainly less steep than say theme design or hacking for WordPress, in my experience.

With GitHub Pages using Jekyll, it's common to see many Jekyll users sharing their Jekyll blog sources openly via GitHub.

There's a listing of Jekyll-generated sites in the documentation, along with links to their respective GitHub repositories when available.

These are great to browse through for some knowledge on how other Jekyll users have built their web sites.

Learning curves aside, if you're after a simplistic blog tool construction-wise that does not require multiple users or a fully featured web publishing interface, then Jekyll could easily do the trick.

(Be assured, the sophistication of the final output for Jekyll can generate beautiful multi-layout blogs akin to WordPress.)

Ultimately, I changed to Jekyll because WordPress seemed like an overkill and I was up for learning a new platform.

I hope this article serves to help you if you're experiencing a similar predicament.

Feature image
by macaroni1945.