jekyll collections for structured content types

By -

What Are Jekyll Collections

Jekyll collections are a powerful feature that let you define custom content types beyond posts and pages. This is useful when your site needs structured content like documentation, team members, case studies, tutorials, or portfolios—each with its own layout and logic.

Why Use Collections Instead of Posts

Using collections helps separate content logically and provides better maintainability. For example, a blog that also showcases products or tutorials can place these in separate folders with different formatting needs, making the site more organized and scalable.

How to Set Up a Collection in Jekyll

Step 1: Define the Collection in _config.yml

To define a new collection called tutorials, add the following to your config file:

collections:
  tutorials:
    output: true
    permalink: /tutorials/:path/

The output: true option ensures that Jekyll builds HTML pages from your collection items.

Step 2: Create a Directory

Inside your Jekyll root, create a folder named _tutorials. This naming convention is required for Jekyll to recognize it as a collection folder.

mkdir _tutorials

Step 3: Add Markdown or HTML Files

Each file represents one item in the collection:

---
title: "Getting Started with Jekyll"
difficulty: beginner
layout: tutorial
---
Learn how to install Jekyll and create your first site.

Creating a Layout for Collection Items

Create a layout like _layouts/tutorial.html that renders your collection content. It might look like this:

{% raw %}

{{ page.title }}


Difficulty: {{ page.difficulty }}


{{ content }}

{% endraw %}

Displaying Collection Items

You can display all tutorials on an index page with:

{% raw %}

    
  {% for tutorial in site.tutorials %}
    
  • {{ tutorial.title }} - {{ tutorial.difficulty }}
    • 
  {% endfor %}


{% endraw %}

Example Use Cases for Jekyll Collections

1. Product Pages

List product specs, reviews, and downloads with different layouts than blog posts.

2. Documentation Sections

Break up user guides into separate collection files that follow a specific structure.

3. Portfolio Projects

Showcase your design or development work with detailed project pages.

Case Study: Developer Portfolio Site

A freelance developer created a Jekyll site with three collections: _projects, _clients, and _snippets. This setup helped separate personal projects from paid work and allowed custom filters and category pages per type. The site felt more structured and increased time-on-site metrics by 40%.

Managing Complex Data with Front Matter

Collections support rich front matter. You can include nested data like arrays or objects to store FAQs, technologies used, or metadata:

---
title: "REST API Tutorial"
tags: [api,backend,web]
tools:
  - name: Postman
    use: Testing
  - name: Express
    use: Server
---

Pagination and Collections

Jekyll does not support native pagination for collections, but you can use the jekyll-paginate-v2 plugin to add pagination functionality to collections.

Best Practices for Collections

  • Use collections to group similar content types that don’t belong in blog posts.
  • Always give collections their own layout to keep templates clean.
  • Use rich front matter to make filtering and displaying items easier.
  • Combine with data files or Liquid logic for powerful display options.

Conclusion

Jekyll collections are essential for building more advanced, structured sites. Whether you're building a portfolio, documentation site, or something entirely custom, collections help you organize your content clearly, enabling better design, readability, and SEO.