By Taylor Jones

Getting Started with Jekyll Collections

By Taylor Jones


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.

  - 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.

    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 limit:3 %}
        <img src="{{ album.thumbnail-path }}" alt="{{ album.title }}"/>
        <a href="{{ album.url }}">{{ album.title }}</a>
        <p>{{ album.short-description }}</p>
{% 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.


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.

  • Matt M.

    Would you mind sharing the source code for this example? I’m having a hard time figuring out where the loop gets its data from. I have a feeling it comes from the markdown files, but you don’t provide a sample of their code.

    • Source code for the example can be found here:

      There you’ll see the loop on index.html. You’re correct, it does get the data from the metadata defined in the markdown files. When you define the collection in the _config.yml, you then have access to that metadata by referencing site.collectionName in a liquid templating block. In this case, its “”

  • Matt M.


  • DanBangWTFRajib

    I love Jekyll for its simplicity…

    Even I have worked with Jekyll several times before haven’t used Collections, and had to work around for something like that, like path linking.

    Collection is something, I need to explore more and try to implement in scenarios related with such collections, thank you about making us aware of such great thing and sample of how it works. Glad to learn about collections in Jekyll

  • Su

    Hey, thank you for this article. However, I’m not able to get the collections to work. On the home page there isn’t anything under the h1 `Albums`.

    I’ve verified that I’m using Jekyll 2.4, and I’m testing this on your GitHub repo that you posted in another comment.

    Any ideas?

  • Nathan Jessen

    The collections are working just fine for me and each album is being placed on homepage list and as an individual page with link from the homepage.

    Is your console outputting any errors? And does your local copy contain everything that is in the repo?

  • RedYeti

    Thanks for the simple explanation. I’m having a hard time figuring out how Jekyll knows what an ‘album’ is though. The only time anywhere in the source ‘album’ is mentioned is in the Liquid loop on the homepage. Could you use anything in place of that?

    • Yes, in the for loop defined on the homepage, the variable “album” can be whatever you’d like it to be. If you had a “cookbook” collection of recipes, you could say:

      {% for recipe in site.cookbook limit:3 %}

      This is the basic structure of the for iteration tag in Liquid

      {% for item in array %}

      You can read more about Liquid’s iteration tags in the documentation.

    • Eric Tirado

      ‘album’ stands for a single item of the site.collection you’re drawing from.
      Like Taylor said, you can name this anything you want. This handle is what you will use through the liquid loop to inject each item of your post into the loop. So ‘album.title’ will draw the title from the YAML header of each markdown file inside the collection you’re drawing from.

  • makingthings

    Hi thanks for this tutorial. I downloaded the github repo and ran jekyll serve and there was not album content apart from the hard coded album title. Could it be a change in the jekyll API or most probably something dumb I’m doing.

  • How would you access an item’s data set in the file’s front matter?

Get the latest in Ruby, once a week, for free.