Getting Started with Jekyll Collections

Recently, I’ve begun the process of overhauling my portfolio website to give a better sense of who I am and what I do. It’s always a fun time to play around with a personal project and update a showcase of your capabilities as a developer. My first task in redoing my portfolio site was to decide how I was going to build the thing. I decided to use Jekyll. Jekyll 2.0 has recently been released, and with it comes an interesting new feature — Collections. In this article I’ll be giving an overview of what makes Jekyll great, how to quickly get going, and explain the ins and outs of Jekyll Collections. For a primer on Jekyll, check out the documentation. It’s very well done and quite helpful, especially if you’d like to dive deeper into Jekyll’s functionality and features.

What Makes Jekyll Great

In deciding to redo my portfolio site, I knew I wanted something simple and easily customizable. I didn’t necessarily need a database or really any backend for that matter. A CMS solution like WordPress or Craft would be overkill — I just wanted something simple. In my search, I came across Jekyll. It’s simple, light, and blog-ready. It parses Markdown, has built-in code formatting, produces static files, and is even host-able via GitHub. All these (and more!) aspects of Jekyll make it quite easy to work with and the right choice for me. There have been some great improvements in the 2.0 release of Jekyll, the one I’ve been enjoying the most is Jekyll’s collections. First though, lets run through how to get started with Jekyll.

Quickly Setting Up Jekyll

To setup Jekyll, there are a couple requirements. You’ll need Ruby and RubyGems installed, and be somewhat comfortable with the terminal. Also, a common issue you might run into on Mac OSX is not having the most up to date X-Code command line tools. The most up to date command line tools can be found here, in the downloads section of Apple’s developer portal. You’ll need an Apple ID to access the downloads.

With the requirements out of the way, you’re only 4 lines in the terminal away from having a Jekyll project running. Open your terminal, and run these 4 commands:

~ $ gem install jekyll
~ $ jekyll new jekyllTest
~ $ cd jekyllTest
~/jekyllTest $ jekyll serve

In order, here’s what’s going on here:

1. Installs Jekyll to your system.
2. Creates a new directory full of Jekyll boilerplate files.
3. Changes the working directory to the newly created “jekyllTest”.
4. Spins up a server to serve those files at localhost:4000.

Out of all the boilerplate files put into the working directory, the main file we’ll be most concerned about for setup is config.yml. config.yml is the global configuration file for Jekyll. In this file, you can specify build options, server options, declare collections, and set site-wide metadata using YAML front matter. The ability to use YAML front matter is a particularly nice feature of Jekyll. The term front matter actually comes from the world of book design. In books, front matter is at the beginning of the book and holds all the metadata associated with a book: title, author, publisher, table of contents, and so on. Similarly, we can use front matter in YAML format to declare site-wide metadata inside the _config.yml file, and page-specific metadata in .markdown files. This metadata can then be referenced as variables using the liquid templating engine used by Jekyll.

What Are Collections?

Collections are sets of documents that have the same functionality as posts. Collections have the power of posts, but it’s all in your hands. One thing to note is that, for now, collections don’t support pagination like posts, although collections of documents can be rendered individually as pages. They can also be rendered in a list using the Liquid templating engine built into Jekyll. Collections have their own namespace throughout your site with customizable metadata and properties.

Collections work by Jekyll reading in your defined collection in the _config.yml file on site build. Jekyll adds the collection’s document’s YAML front matter to the site’s global Liquid templating variables, and optionally renders each document into its own page. Collections are a great use for any arbitrary set of content you’d like to organize on your site. Good examples for a collection are projects you’ve worked on, organizers of an event, a collection of music, API documentation, etc. We’ll use a collection of music as an example.

Configuring Collections

The first step to configuring collections is to tell Jekyll that you have a collection in the _config.yml file.

collections:
  - music

Now, add a folder to the root of the project directory with the same name as the collection. Be sure to prefix the folder with an underscore. Add some documents in markdown format to the collection’s folder.

If you so choose, you can specify to render a page for each document by modifying the _config.yml as so.

collections:
  music:
    output: true

Collections in Action

Now that the collection is defined and content has been added to the collection, it can now be accessed on any page within the Jekyll site. As an example, the most recent additions to your collection can be shown on your homepage using Liquid templating syntax. Any custom YAML front matter declared in each document can be accessed as well.

{% for album in site.music limit:3 %}
      <li>
        <img src="{{ album.thumbnail-path }}" alt="{{ album.title }}"/>
        <a href="{{ album.url }}">{{ album.title }}</a>
        <p>{{ album.short-description }}</p>
      </li>
{% endfor %}

This provides a great way to show related images, titles, etc. within a list of documents. You can use the built in url attribute to link to a document’s rendered page.

Conclusion

Jekyll is a great solution for building small, static sites. It is worth mentioning that it will struggle to compete with sites that need a robust backend – including data manipulation and search. This is something to keep in mind when debating on choosing Jekyll for your next project. That being said, Jekyll’s setup is quick and it has some configurable options that allow you to specify how you’d like the site to work. The requirements are minimal and the quick setup functionality gives you a fully functioning site.

The recently added collection functionality has a straightforward declaration configuration as well as some customizable attributes, allowing you to render your documents into their own pages. Utilizing the configuration parameters, as well as YAML front matter, gives you the ability to render the documents in different areas of the site. Jekyll really excels in the area for which it’s been designed, and the functionality of collections has opened up the doors to leverage sites with more content.