Collections in Jekyll are quite similar to blog posts but have a slightly different use case. Let's explore in this lesson.
Clone: git clone https://github.com/CloudCannon/jekyll-learn-blog-template.git
Starter branch: git checkout collections-intro-start
Finished lesson: git checkout collections-intro-finish
The difference between posts and collections
Using collections on your pages
Outputting collections as standalone pages
Collections in Jekyll are quite similar to the posts that we created in the previous lesson. So what’s the difference? Here’s a simple summary:
The keyword to remember is “group”. If you have a series of items that fall under a certain category/theme - like profiles for people/employees or recipes/menu items - a collection is probably suitable. Often, the content of items can all be displayed on the same page, or also have its own page, whereas a post should only take up its own page.
Let’s reinforce the point by explaining how collections are used in this code-along project:
Hopefully the purpose of collections is clearer. Now let’s put them into action.
Technically, we could simply put a collection of items into front matter on a specific page that uses them. However, it would be better to access these items across multiple pages. This makes the content flexible and easier to maintain. Jekyll provides simple conventions to do this - no surprises here.
First, let’s finally visit our
_config.yml file. This file stores our “global” variables (accessible from any page), and we intend to make our collections global too. Add this to the
Now that we have the collection name recognized, let’s add the actual collections. Create a folder at the root of the project that matches this variable name, with an underscore -
_birds. This is the convention to follow for collections.
We can now add collection documents to this folder. Again, like posts, it is also most common to use Markdown documents. If you are using the code-along project, the contents for collection items can be found in
collections.zip in the root of the project. Simply unzip the contents into _birds.
Now that we have our collection set up, let’s use it. For this example, we are going to display them in a gallery view. For this purpose, we will create gallery.html in the root of the directory, with the following front matter:
Now all we need to do is loop through our collection, which has been made a global “site” variable in our
_config.yml file. To begin, add the following content below the front matter in
Now we can see the images and the description in our gallery, which is great.
If you are using the code-along site, for something that looks a bit nicer and makes full use of the collection content, you can check out the “finished” repository or use this code:
Feel free to play around with the collections and logic. Now we can see our collection as a gallery when we run our server.
It is also possible to output your collection items as independent pages. To do this, we will need to do three small things:
First, change the collection object in
_config.yml to the following:
Now when Jekyll builds the site, it will create (output) pages for each item, but only basic HTML content. Let’s create another layout -
item.html - that will be used for showing each item:
As with posts, we need to add which layout to use in the front matter (this has already been done note
layout: item in each collection item).
Lastly, to access our items, we will also update
gallery.html to use the newly created collection links (look for HTML comment):
In our browser, we can now view both the item preview and the full item content from the links.
Hopefully it should now be clear why you might want to use collections over posts. But let’s move onto an even lower-level type of content - data files.