jekyll collections for scalable content types

What Are Jekyll Collections

Jekyll collections are a powerful way to organize and manage custom content types beyond regular blog posts and pages. They allow developers to structure content logically—for example, portfolios, documentation pages, team member profiles, or reusable data sections—while maintaining Jekyll's simple static site generation process.

Why Collections Matter in Scalable Static Sites

• Enable clear separation of different content types
• Support nested navigation and dynamic rendering
• Allow custom output formats and URL patterns
• Improve maintainability for larger or multi-author projects

How to Define a Collection

Collections are defined in the _config.yml file:

collections:
  tutorials:
    output: true
    permalink: /tutorials/:title/
  team:
    output: false

Each collection gets its own folder prefixed with an underscore:

• _tutorials/ → output to HTML pages
• _team/ → used for data, no HTML output

Structuring Content Inside a Collection

Each markdown or HTML file inside a collection folder must include front matter. For example, _tutorials/seo-basics.md:

---
title: SEO Basics for Beginners
level: beginner
category: on-page
layout: tutorial
---
Content of the tutorial goes here.

Collection Metadata in Front Matter

You can customize what data is available to each item through front matter, then access that in your templates or index pages.

Rendering Collection Pages

To loop through all items in a collection:

{% raw %}

  {% for tutorial in site.tutorials %}
    

      {{ tutorial.title }} - {{ tutorial.level }}
    
  {% endfor %}

{% endraw %}

Filtering and Sorting Collections

You can combine Liquid logic and filters to group or sort content:

{% raw %}
{% assign beginner_tutorials = site.tutorials | where: "level", "beginner" %}
{% for tutorial in beginner_tutorials %}
  
{{ tutorial.title }}
{% endfor %}
{% endraw %}

Use Case 1: Team Members Listing

Define a _team collection with entries like _team/jane-doe.md:

---
name: Jane Doe
role: SEO Strategist
bio: Jane has 10 years of experience...
image: /assets/team/jane.jpg
layout: null
---

Then render them inside a page:

{% raw %}
{% for member in site.team %}
  

    
    
{{ member.name }}
    
{{ member.role }}
    
{{ member.bio }}
  
{% endfor %}
{% endraw %}

Use Case 2: Modular Documentation

Create a collection like _docs with nested folders for versioned or modular documentation:

_config.yml
collections:
  docs:
    output: true
    permalink: /docs/:path/

This allows version control by folder structure: _docs/v1/getting-started.md, _docs/v2/getting-started.md.

Customizing Layouts per Collection

Each collection item can specify its own layout, or you can define a default layout for that collection in its template:

{% raw %}
---
layout: tutorial
---
{% endraw %}

Then build custom layouts like _layouts/tutorial.html to reflect the structure or metadata of that collection.

Pagination for Collection Pages

Jekyll’s native pagination works only for posts. To paginate collections, you need third-party plugins or manual slicing using Liquid logic. For example:

{% raw %}
{% assign tutorials = site.tutorials | sort: "date" %}
{% for tutorial in tutorials offset:0 limit:5 %}
  
{{ tutorial.title }}
{% endfor %}
{% endraw %}

Mixing Data Files and Collections

Collections can be enhanced with YAML/JSON data files to connect static data with dynamic content. For example, a tutorial can reference tools from _data/tools.yml and display them per item.

Managing Large Projects With Multiple Collections

• _tutorials: for learning content
• _products: for product listings
• _clients: for testimonials
• _resources: for downloadable assets

Each collection can be versioned, sorted, filtered, and styled independently, giving developers complete control over site structure.

Case Study: A Scalable SaaS Documentation Site

A SaaS company used Jekyll collections to build a developer documentation portal with the following features:

• Separate folders per API version using collections like _v1_docs and _v2_docs
• Sidebar navigation auto-generated from the collection's folder structure
• Global variables injected from data files to avoid hardcoding URLs and labels

The result was a fully static site deployed on GitHub Pages, version-controlled and easy to maintain without a CMS.

Conclusion

Jekyll collections offer unmatched flexibility in structuring and scaling content. Whether you're building a documentation hub, multi-format blog, portfolio site, or directory, collections allow you to isolate concerns and organize your content like a CMS—without the complexity. Mastering collections is essential for any serious Jekyll developer aiming to create maintainable and professional-grade static sites.