Implementing Jekyll Collections: A Step‑by‑Step Guide to Custom Content Types

Desired Outcome

By the end of this article you will have a fully configured Jekyll collection called _staff that stores staff biographies, automatically renders each biography as an HTML page, and lets you filter and sort the data in Liquid templates.

Prerequisites

• Jekyll 4.x installed locally (or in your CI environment) and a site that already builds without errors.
• Basic familiarity with YAML and Liquid syntax.
• Access to the project root directory (e.g., via SSH or a local editor).
• Administrative permissions to edit _config.yml and to restart the Jekyll server.

Step 1: Create the Collection Folder

In the root of your Jekyll project, add a folder named _staff. The underscore prefix tells Jekyll that this folder contains a collection.

mkdir _staff

Place a few Markdown files inside. Each file starts with a YAML front matter block that describes the staff member.

---
name: Jane Doe
title: Lead Designer
department: Creative
---

Jane has over 10 years of experience in UI/UX design...

Step 2: Register the Collection in _config.yml

Open _config.yml and add a collections section. The key staff will be used to access the collection in Liquid.

collections:
  staff:
    output: true
    permalink: /staff/:title/

Key points:

• output: true tells Jekyll to write each item as a standalone page.
• The permalink pattern defines the URL structure for each page.
• Indentation must be two spaces per level; otherwise Jekyll will ignore the section.

Step 3: Restart the Jekyll Server

After editing _config.yml, restart the local server so the new collection is loaded. If you’re using jekyll serve, stop the process and run it again.

Ctrl+C
jekyll serve

Step 4: Verify the Collection Exists

Open the browser at http://localhost:4000/_site/ and confirm that staff appears in the site.collections list. In a page template you can also print the collection count:

{{ site.collections.staff.docs.size }} staff members found.

Step 5: Render Collection Items in a Template

To display all staff biographies on a single page, create staff.html in the root with the following Liquid loop:

---
layout: default
title: Our Team
---


  {% for member in site.staff %}
    

      {{ member.name }} – {{ member.title }}
    
  {% endfor %}

When you navigate to /staff.html, you should see a list of links pointing to the generated pages like /staff/jane-doe/.

Step 6: Filter and Sort the Collection

Collections support filtering by front‑matter fields. For example, to list only designers:

---
layout: default
title: Designers
---


  {% assign designers = site.staff | where: "department", "Creative" | sort: "name" %}
  {% for member in designers %}
    
{{ member.name }} – {{ member.title }}
  {% endfor %}

Expected Checks

1. Build succeeds: jekyll build completes without errors.
2. Generated pages: _site/staff/jane-doe/index.html exists.
3. Permalink matches pattern: URL ends with /staff/jane-doe/.
4. Liquid loop outputs correct counts: the page shows the expected number of staff members.

Recovery Options

• If the build fails after adding the collection, double‑check the YAML indentation in _config.yml and ensure the collections key is correctly nested.
• To revert the collection, delete the _staff folder and remove the staff entry from _config.yml, then restart the server.
• Large collections can slow builds; consider using exclude in _config.yml or splitting the data into smaller files.

Limitations & Practical Checks

• Jekyll processes every file in a collection during each build, so very large collections increase build time linearly.
• Only files inside the collection folder are treated as collection items; subfolders are ignored unless output: true is set and the subfolder contains valid Markdown files.
• To confirm that the collection is active, add {{ site.collections | inspect }} to a debug page and verify that staff appears in the output.

Conclusion

Collections give you a clean, structured way to manage custom content types in Jekyll. By following the steps above you can add a new collection, configure its output, and use Liquid to display the data exactly how you need it.