Project Inquiry
Published on

Environments in Jekyll (aka JEKYLL_ENV)

Jekyll is an excellent tool to generate simple websites and blogs. Its documentation summarizes it as follows:

Jekyll is a simple, blog-aware, static site generator.

Why Jekyll?

Firstly, it is designed form the ground up for developers. Working on Jekyll websites boils down to editing plain text files. You don’t have to rely on a bloated Content Management Systems like WordPress.

Secondly, the fact that it only generates static websites, makes the deployment of your websites as trivial as it can be. You don’t have to worry about anything being executed on your servers (or even setting up a database). A webserver like nginx or Apache is all you need.

Thirdly, because you are working with plain text files, you can track your website’s history with the version control system of your choice.

Last but not least, it’s easy to extend with plugins. Jekyll itself is written in Ruby and plugins are nothing more than ordinary Ruby classes. Just implement your plugin with Ruby and place it in your website’s _plugins directory.

Enough with the advertising. Let’s get down to business.


Many web-related Ruby projects incorporate the concept of “environments” and so does Jekyll (since version 2.1.0). I discovered the feature only a couple of weeks ago and Jekyll’s documentation doesn’t seem to mention it. That’s why I decided to devote an article to the topic…

Environments are the way to go if you want your application to behave differently depending on “external circumstances”. For instance, if you create a new Ruby on Rails project (i.e. rails init [name]), it’s automatically pre-configuring three environments for you: development, test, and production. Most importantly, the environment is how your Rails application picks the right database to connect to.

Even though, Jekyll websites are static after they’ve been built, they are not necessarily self-contained. It’s true that there’s no database involved, but that doesn’t mean that you cannot integrate external services into your website. Google Analytics is a great example for the purpose of this article, because it’s a realistic requirement to have it enabled in production and disabled in development. After all, you probably want to track your visitors and not yourself during development.

If you build your Jekyll website, it’s possible to specify the environment it’s using for the build with the JEKYLL_ENV environment variable:

$ JEKYLL_ENV=production jekyll build

If you don’t set JEKYLL_ENV explicitly, it defaults to development.

You can access the current environment from within your website’s templates with the Liquid variable jekyll.environment. That’s really the last missing piece of the puzzle, because now you have the means to act differently depending on the current environment.

Continuing the example with Analytics from above, you could do the following in your website’s main layout template:

<!DOCTYPE html>
    {{ content }}
    {% if jekyll.environment == "production" %}
        // JavaScript snippet supplied by Google goes here...
    {% endif %}

As you can see, we are including the JavaScript snippet for Analytics if and only if the current environment is production. As I’ve pointed out before, the default environment is development. Therefore, Analytics is always disabled unless you’ve explicitly set JEKYLL_ENV to production.

Mission accomplished. Thank you for reading!

Software: Jekyll 2.5.3