Managing Custom Content Types with Jekyll Collections

The Problem: Beyond Posts and Pages

Standard Jekyll sites rely on _posts for chronological content and index.html or about.html for static pages. However, many projects require structured content that doesn't fit a date-based timeline—such as team member profiles, product catalogs, or a library of documentation. Creating these as standard pages often leads to a cluttered root directory and makes it difficult to query specific groups of content in a template.

The Takeaway: Use Jekyll Collections to define custom content types. This allows you to isolate specific data sets in their own directories, apply unique permalink structures, and iterate through them using Liquid loops without mixing them with your blog posts.

Prerequisites

• A functional Jekyll installation (v3.0 or later).
• Basic familiarity with YAML front matter.
• Administrative access to the project root directory to create folders and edit _config.yml.

Step 1: Define the Collection in Configuration

Jekyll does not automatically detect new folders starting with underscores; you must explicitly register the collection in your configuration file. Open _config.yml and add a collections key.

collections:
  staff:
    output: true
    permalink: /team/:name/

Configuration Breakdown:

• staff: The name of the collection. This determines the folder name (_staff) and the Liquid object name.
• output: true: Tells Jekyll to render each file in the collection as a standalone HTML page. Set this to false if the collection is only meant to be used as data for a list on another page.
• permalink: Defines the URL structure. In this example, :name is a placeholder that Jekyll replaces with the filename.

Step 2: Create the Content Directory

Create a directory in your project root that matches the collection name, prefixed with an underscore. If you named your collection staff, the folder must be _staff.

Add a Markdown file to this directory. Every file in a collection must contain YAML front matter to be processed.

---
name: "Jane Doe"
role: "Lead Engineer"
bio: "Expert in distributed systems."
---

# Jane Doe
Jane has been with the company for five years...

Step 3: Accessing Collection Data in Templates

To display your collection content, use the site.collections object. Because collections are stored as arrays, you must use a Liquid for loop to render them.

Add the following code to a page (e.g., team.html) to create a directory of your staff members:

<ul>
  {% for member in site.collections.staff %}
    <li>
      <a href="{{ member.url }}">{{ member.name }}</a> - {{ member.role }}
    </li>
  {% endfor %}
</ul>

Diagnostic Decision: Output True vs. False

Choosing the output setting changes how Jekyll handles the build process. Use the table below to decide which setting fits your use case:

Verification and Testing

Because _config.yml is only read at the start of the build process, you must restart your server after adding a collection. Run the following command in your terminal:

bundle exec jekyll serve

Checks:

1. URL Check: Navigate to http://localhost:4000/team/jane-doe/. If you see a 404, verify that output: true is set in _config.yml.
2. Data Check: View the team.html page. If the list is empty, ensure the folder is named _staff (with the underscore) and that the files contain valid YAML front matter.

Limitations and Risks

• Build Performance: Every file in a collection is processed during the build. Collections with thousands of files can significantly increase build times.
• Naming Conflicts: Ensure your collection name does not clash with reserved Jekyll keywords or other existing collections.
• Directory Naming: Omitting the underscore (e.g., naming the folder staff instead of _staff) will cause Jekyll to treat it as a standard directory, ignoring the collection configuration and failing to apply the custom permalinks.

Rollback Procedure

To remove a collection and revert the site state:

1. Delete the _collection_name directory.
2. Remove the corresponding entry from the collections block in _config.yml.
3. Restart the Jekyll server to clear the internal site object cache.