Using Jekyll Collections to Organize Custom Content Types

The Problem: Custom Content Beyond Posts

When a site needs distinct content groups—such as a team directory, product catalog, or portfolio—relying on the standard _posts folder can become unwieldy. Dates in filenames, automatic chronological sorting, and rigid URL patterns limit flexibility. Jekyll Collections let you define separate content buckets with their own file structure, metadata handling, and URL schemes.

Desired Outcome

Define a new collection, store Markdown files in a dedicated folder, and render the items with a Liquid loop that respects custom permalinks and metadata.

Prerequisites

• Jekyll 4.x installed locally (or a CI environment that supports Jekyll 4.x). Collections have been available since Jekyll 2.0, but the example uses the 4.x syntax.
• Basic familiarity with YAML for _config.yml and Liquid templating.
• Write access to the site root to modify configuration and create directories.

Step 1: Register the Collection in _config.yml

Add a collections block. Each collection can be configured individually. The snippet below creates a staff collection that outputs a page for each member and places the pages under /team/.

# _config.yml
collections:
  staff:
    output: true
    permalink: /team/:path

Key points:

• output: true tells Jekyll to generate an HTML page for every item. If you only need the data for templates, set this to false.
• permalink defines the URL structure. :path is replaced by the file name (without the extension). If omitted, Jekyll uses the default /staff/:path path.

Step 2: Create the Content Folder

Jekyll expects the folder name to match the collection key and to be prefixed with an underscore. From the site root run:

mkdir _staff

Step 3: Add Markdown Files with Front Matter

Each file must contain YAML front matter. The front matter keys are arbitrary and can be queried in Liquid. Example:

# _staff/jane-doe.md
---
layout: staff-profile
name: Jane Doe
role: Lead Engineer
email: [contact removed]
---
Jane has over ten years of experience in distributed systems and has led several high‑profile projects.

Ensure that the staff-profile layout exists in _layouts or use a default layout. If the layout is missing, Jekyll will fall back to the global default layout but you may see a warning during build.

Step 4: Render the Collection with Liquid

To display a list of all staff members, add the following loop to a page or layout. The loop iterates over site.staff, which is automatically populated by Jekyll.

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

When the site is built, each item’s url will resolve to the path defined in the permalink setting.

Verification Checklist

1. Restart the server: After changing _config.yml, run bundle exec jekyll serve again to ensure Jekyll re‑indexes the new collection.
2. Confirm output files: In the output directory (default _site), verify that /team/jane-doe/index.html exists.
3. Validate URLs: Open http://localhost:4000/team/jane-doe in a browser. The page should display the content from jane-doe.md and use the staff-profile layout.
4. Check the loop: On the page containing the Liquid loop, confirm that the list renders at least one <li> element. If the list is empty, double‑check YAML indentation in _config.yml and that the directory name matches the collection key.

Limitations & Considerations

• Large collections (hundreds of files) can increase build time because each file is parsed and rendered. If build performance becomes an issue, consider disabling output: true and rendering items only within a list page.
• All collection data is loaded into the site object during the build. Extremely large datasets may stress memory limits in CI environments.

Rollback Procedure

1. Remove the staff block from the collections section in _config.yml.
2. Delete or rename the _staff directory to avoid confusion.
3. Restart the Jekyll server to clear the site graph.