Troubleshooting Missing Content in Jekyll Collections

The Problem: Empty Collection Loops

You have defined a custom collection in Jekyll to handle structured content—such as a team directory, a portfolio, or a product catalog—but the content is not appearing on the page. Despite the files existing in the project folder, your Liquid loop (e.g., {% for member in site.staff %}) returns nothing, or the build process completes without any errors but leaves the target page blank.

Diagnostic Matrix

Use this table to match your symptoms to the most likely cause before performing deeper checks.

Symptom	Likely Cause	Diagnostic Check
Loop returns 0 items	Naming Mismatch	Compare _config.yml key to folder name
Specific files missing	Missing Front Matter	Check top of .md or .html files for ---
Build failure/crash	Reserved Keyword Conflict	Check if collection name is a Jekyll internal term
Slow build times	Dataset Volume	Check total file count in collection folder

Step-by-Step Verification Process

Follow these checks in order to isolate where the data pipeline is breaking. These steps assume you are using Jekyll 4.x.

1. Validate Configuration and Directory Alignment

Jekyll requires a strict mapping between the configuration file and the file system. If you define a collection as staff, Jekyll looks specifically for a directory named _staff (with a leading underscore) at the root of your project.

• Open _config.yml and locate the collections: key.
• Ensure the indentation is correct (two spaces).
• Verify the directory name matches exactly. Example: If your config says collections: [staff], your folder must be /project-root/_staff/.

2. Inspect Front Matter Requirements

Files inside a collection directory are not automatically treated as data. For Jekyll to parse a file as a document and add it to the site object, it must contain YAML front matter.

Check your files for the following structure at the very top:

---
title: "Jane Doe"
role: "Lead Engineer"
---
Content starts here...

If a file lacks these triple-dash delimiters, Jekyll treats it as a static asset. It will be copied to the output folder but will be ignored by any site.collection_name Liquid loop.

3. Verify Object Access in Liquid

There is a critical distinction between accessing the collection metadata and the actual documents. Using the wrong variable will result in an empty output.

• Incorrect: site.collections.staff (This returns the collection object, not the list of documents).
• Correct: site.staff (This returns the array of documents within that collection).

Practical Verification Example

To diagnose exactly how many documents Jekyll is recognizing, insert a debug line into your layout or page template. This bypasses CSS or HTML rendering issues and tells you if the data exists in memory.

Run this in your HTML template:

<p>Debug: Collection size is {{ site.staff | size }}</p>

Execution and Check:

1. Run bundle exec jekyll serve from your terminal.
2. Navigate to the page in your browser.
3. If the output is Debug: Collection size is 0, the issue is in _config.yml or Front Matter.
4. If the output is Debug: Collection size is 5 but nothing shows in your loop, the issue is in your Liquid syntax.

Limitations and Performance Risks

While collections are powerful, they are processed entirely in memory during the build phase. If your collection grows to thousands of files, you will notice a significant increase in build times and RAM usage. For datasets exceeding a few hundred entries, consider using a dedicated headless CMS or a JSON-based data file in the _data folder, which has different processing overhead.

Rollback and Recovery

If you have renamed directories or changed configuration keys and the site is no longer building correctly:

1. Revert the _config.yml collection list to its previous state.
2. Rename the _collection_name folder back to its original name.
3. Clear the Jekyll cache by running bundle exec jekyll clean to ensure no stale metadata is interfering with the build.