Developer

Jekyll: A quick and dirty solution for building static HTML sites

Jekyll transforms text and markup into a static website. Read about the various advantages of using Jekyll, and how to get it up and running in minutes.

jekylllogo061914.png
Image: Jekyll

Designing, building, and publishing a website is time-consuming when using technologies such as ASP.NET and Ruby on Rails because there are so many components to making sure everything works as planned. That's fine for full-featured applications, but there are times when you want to push out a simple site using basic web standards (HTML, CSS, and JavaScript). This is where Jekyll enters the picture, as it provides a quick and painless solution to building a simple site.

Advantages to using Jekyll

I never gave much thought to website generation tools until my recent experience with GitHub Pages — as it turns out, Jekyll is the engine that powers GitHub Pages.

Jekyll is a static website generator. It compiles (or generates) a complete, static website via markup and template files. In addition, it has a plugin system that allows you to create custom generated content specific to your site. The plugin system is not directly supported on GitHub Pages, but there are workarounds. You may be thinking a static HTML site is a step backward in time, but there are occasions when it is the perfect solution.

Blogging is one of the more popular Jekyll applications. With a blog, the content is the key ingredient, and a framework such as Bootstrap can be used to make it visually appealing. Jekyll simplifies the process of creating the website (or blog), so you can focus on the content. In addition, this simplicity eases maintenance and leads to a portable solution — after all, it is much easier to move an HTML-based site than something custom (PHP, ASP.NET, Ruby, etc.) with a database backend.

Also, the odds of an HTML solution being obsolete are slim. The GitHub integration provides in-place source control.

A final advantage is the text formatting via Markdown. This is new to me, but it is a powerful solution to working with text.

Get Jekyll up and running in minutes

Jekyll is a Ruby gem, so Ruby is required.

  1. Install Ruby and the Ruby Development Kit.
  2. Install Jekyll gem (gem install jekyll).

If you're using a flavor of UNIX or Linux, you are good to go at this point. For this article, I went the non-traditional route and used my Windows 7 development machine. Windows poses challenges with making Jekyll act as expected; I suggest going to the Jekyll site for good insight into Windows configuration. Basically, you follow the normal path of configuring Ruby on Windows. Once Jekyll is installed, you have to tweak it to get it working locally.

Jekyll-based sites have a file that stores all configuration data (_config.yml). One item used by UNIX/Linux installations is a Python-based highlighter add-on called Pygments. I did not attempt to set this up in my Windows environment. While you could install Python or use other highlighter options, I used a configuration option to disable the highlighter feature — just add this line to the _config.yml file:

highlighter: false

Here is an overview of what else is included in a basic Jekyll site:

  • _includes: This directory includes all of the partial views that can be used across pages via the include feature.
  • _layouts: This directory contains the templates used by the site. You can have one template for everything or different layouts for pages or sections.
  • _posts: This directory contains the content or posts for the site. The required file name format is YEAR-MONTH-DAY-TITLE.MARKDOWN (or the .MD file extension can be used). An example post for June 9th would be 2014-06-09-Example.md.
  • _site: This directory is where the generated HTML site is placed once Jekyll does its thing.
  • index.html: The entry point of the site. It, along with any other HTML or text files, will be transformed by Jekyll.
  • css: CSS files used by the site. This is not compiled; it is copied directly to the generated site. Every file or folder that does not begin with an underscore will be copied to the generated site.

The front matters

A key feature of Jekyll is the front-matter concept — this is a special YAML-formatted block at the beginning of files. Any file that contains this front matter will be processed by Jekyll as a special file. Basically, it is a block defined by triple-dashed lines. Everything between the first and last set of triple dashes are variables processed by Jekyll. Between these dashes are predefined (or custom) variables. A good example is individual content or post files (_posts directory), which use the following front matter:

——

layout: post

title: "Example Content"

date: 2014-06-09 15:50:00

categories: Jekyll TechRepublic

—-

It gets more complex than these basic headers, as the Liquid templating engine has many supported features. Refer to the online documentation on how to work with content and markup.

Serving it up

The Jekyll engine is started via the simple command shown in Figure A (from Windows); Figure B shows the sample site opened in a browser. It is worth examining the contents of the _site directory to see what Jekyll actually generates — Figure C shows what is generated for my sample site. The actual posts (or content) are located in subdirectories within the Jekyll directory shown at the bottom of Figure C.

Figure A

jekyllfiga061814.jpg

The Jekyll command is used to start Jekyll.

Figure B

jekyllfigb061814.jpg

The basic sample Jekyll site viewed in Google Chrome.

Figure C

jekyllfigc061814.jpg

The _site directory contains the Jekyll-generated content.

Only the beginning

If you need to generate a simple site with content and CSS formatting, Jekyll provides a powerful tool. With that said, it is not a solution for every project, so make sure you understand what you need and what it offers before diving in.

I just scratched the surface, as there is so much more to cover with GitHub integration as well as ways to enhance Jekyll-based sites, which I'll cover next week.

Also read

About

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...

Editor's Picks