Use Jekyll collections for structured non-blog content

Problem and useful answer

If your site needs team member profiles, documentation topics, or portfolio pieces, putting them in _posts/ forces date-based URLs and archive pages you may not want. Jekyll collections are the built-in alternative: they group documents outside _posts, render each document as its own page when enabled, and expose the group to Liquid templates for indexes and cross-references.

Useful answer: configure a collection in _config.yml, place Markdown files in the matching underscore directory, and set output: true so Jekyll writes HTML files to _site.

Worked configuration: a team collection

This example assumes a standard Jekyll site using Jekyll 4.x. Collections are core behavior and do not require plugins.

1. Declare the collection

Add this to _config.yml in your site root:

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

defaults:
  - scope:
      path: ""
      type: team
    values:
      layout: team-member

team is the collection name. Jekyll looks for source files in _team/. output: true tells Jekyll to write each document to _site; without it, the documents exist in Liquid but no HTML files are emitted. permalink: /team/:name/ builds URLs from the filename without its extension. The defaults block applies layout: team-member to every document in the team collection so you do not repeat front matter in each file.

2. Add a document

Create _team/alice.md:

---
name: Alice Nguyen
role: Senior Engineer
photo: /images/alice.jpg
---

Alice leads the backend team and maintains the deployment pipeline.

Front matter variables become available in layouts as page.name, page.role, and page.photo.

3. Create the layout

Create _layouts/team-member.html:

<!doctype html>
<html>
<head><meta charset="utf-8"><title>{{ page.name }} · Team</title></head>
<body>
  <h1>{{ page.name }}{{ page.role }}

{{ content }} holds the Markdown body; markdownify converts it to HTML inside the layout.

4. List the collection with Liquid

On a team index page, iterate over site.collections.team:

<ul>
  {% for member in site.collections.team %}
    <li><a href="{{ member.url }}">{{ member.data.name }}

site.collections.team is the array of documents in the collection. member.url uses the permalink pattern, and member.data exposes the document's front matter.

5. Build and verify

Run this in your site root directory. No elevated permissions are required; Jekyll writes to the local _site/ folder.

jekyll build

Expected result: _site/team/alice.html exists and contains Alice's rendered profile. A practical check is:

ls _site/team/
grep -l "Alice Nguyen" _site/team/*.html

Risk: jekyll build regenerates _site/ and can overwrite previously generated files in that folder. It does not modify source files under _team/. To start clean, remove _site/ before rebuilding.

Run jekyll doctor after editing _config.yml to catch invalid collection keys or directory mismatches.

Limits and common mistakes

• No output files without output: true. Documents are still available to Liquid, but Jekyll does not write HTML for them.
• Directory name must match. Collection team reads from _team/. A missing or misspelled folder means no documents are picked up.
• Filename becomes the URL slug. :name derives from the filename without its extension. Spaces or unusual characters can produce unexpected URLs.
• Not a blog substitute. Collections lack _posts date-based archive semantics. Use _posts for chronological articles and collections for reference-style content.
• Drafts and future dates. Documents with future dates or draft status are not published unless the build explicitly enables them with --drafts or --future.
• Safe mode. Custom plugins are disabled in safe mode, but core collections behavior is unaffected.

Verification checklist

1. Confirm _team/ exists and contains at least one Markdown file with front matter.
2. Run jekyll doctor and resolve any configuration warnings.
3. Run jekyll build.
4. Inspect _site/team/ for generated HTML files.
5. Open a generated file and confirm it uses team-member layout and displays front matter values.

Collections are best for bounded, structured content that does not need a publication date. If your content is time-ordered, stay with _posts.