Jekyll Collections Explained: Custom Content Types for Static Sites

Section 1: Deconstructing Jekyll’s Content Model

To fully appreciate the architectural significance of Jekyll Collections, one must first understand the foundational content model they were designed to expand. The classic Jekyll paradigm, built for a specific purpose, contained inherent limitations that collections elegantly resolve, transforming the platform from a specialized tool into a versatile static site generator.

1.1 The Classic Jekyll Paradigm: Posts and Pages

In its initial conception, Jekyll’s content architecture was primarily organized around two distinct primitives: Posts and Pages. This binary model served the platform’s origins as a blogging engine exceptionally well but proved restrictive for more complex website structures.

Posts are the cornerstone of Jekyll’s chronological content system. They are defined by a strict set of conventions designed for time-sensitive articles like blog entries or news updates. Each post must reside within a dedicated _posts directory. Furthermore, its filename must adhere to a rigid YYYY-MM-DD-title.md format, which Jekyll uses to parse the publication date and sort all posts in reverse chronological order by default. This date-centric nature is their defining characteristic; posts are fundamentally items on a timeline.

Pages, in contrast, are designed for standalone, non-chronological content. They are useful for static, one-off documents such as an “About Us,” “Contact,” or “Privacy Policy” page. Unlike posts, pages are not bound by a specific directory or naming convention; they can exist anywhere in the site’s source and are typically updated over time to maintain accuracy. Their primary trait is their independence; they do not have an intrinsic relationship with one another.

This established model, while effective for blogs and simple sites, presents a significant architectural challenge when dealing with content that is thematically related but not organized by date. For example, managing a portfolio of projects, a directory of team members, a catalog of products, or a list of recipes falls outside the logical scope of both Posts (as they are not chronological) and Pages (as they are not standalone but part of a distinct group). This limitation represented the core problem that necessitated a new content primitive.

1.2 The Emergence of Collections: A Paradigm Shift

Jekyll Collections were introduced as the official solution to this architectural gap, representing a fundamental paradigm shift for the platform. They provide a mechanism for defining custom types of documents that are grouped together by a shared purpose or theme, independent of publication date. The operative concept behind collections is the “group”. They allow developers to create structured sets of related content, breaking free from the chronological constraints of posts and the unstructured nature of pages.

The introduction of collections marked a significant maturation of Jekyll, elevating it from a “personal blogging tool” to a “general-purpose static site generator.” This evolution has profound implications for the platform’s capabilities and its position relative to other content management systems. Before collections, creating a structured list of non-blog content, like team member profiles, required cumbersome workarounds. With collections, this becomes a native, elegant process. This capability allows Jekyll to effectively build sophisticated documentation hubs, corporate websites with staff directories, artist portfolios, and product catalogs—use cases that were previously difficult to implement cleanly.

Architecturally, collections are analogous to “custom post types” in WordPress or “custom content types” in Drupal, but they bring what has been described as Jekyll’s “zen-like simplicity” to the task. They provide the power of structured content modeling without the complexity of a server-side database or a heavy CMS. This is not merely an incremental feature addition; it is an architectural evolution that redefines Jekyll’s identity and vastly expands its market, making it a viable and powerful choice for a much broader spectrum of web projects.

Section 2: The Anatomy of a Jekyll Collection

Understanding how to effectively implement collections requires a detailed examination of their mechanics, from initial configuration in the site’s primary configuration file to the directory structure and the data processing pipeline that makes their content available throughout the site.

2.1 Defining and Configuring Collections in _config.yml

A collection’s existence begins with its declaration in the _config.yml file at the root of a Jekyll project. This configuration step is mandatory and controls how Jekyll recognizes and processes the collection.

Basic Declaration

There are two primary methods for declaring a collection. The simplest is as a sequence (an array), which is suitable when no additional metadata is needed for the collection itself.

# _config.yml
collections:
 - staff_members

However, a more powerful and common method is to define collections as a mapping (a hash). This approach allows for the configuration of specific metadata and behaviors for the collection, which is essential for most practical use cases.

# _config.yml
collections:
 staff_members:
   # collection-specific metadata goes here

The output: true Directive

The most critical configuration key for a collection is output. By default, Jekyll treats collection documents as data sources; their content is parsed and made available via the site variable, but Jekyll does not generate individual HTML pages for them. Setting output: true fundamentally changes this behavior, instructing Jekyll to render a discrete, public-facing page for each document in the collection.

# _config.yml
collections:
 staff_members:
   output: true

This single setting is a pivotal architectural choice. When output is false (the default), the collection functions as a “content-rich data source,” similar to files in the _data directory but with the added benefit of supporting Markdown content bodies. This is ideal for content like testimonials that might be displayed on other pages but do not require their own URL. When output is true, the collection’s role transforms into a “set of standalone entities,” where each item is a first-class citizen of the site with its own page and unique URL. This is the correct choice for content like team member profiles, portfolio items, or documentation articles, where each item must be a distinct destination. Understanding this duality is the key to mastering the architectural power of collections.

Advanced Configuration Options

The mapping configuration method unlocks several powerful options for fine-tuning a collection’s behavior:

• Custom Permalinks: The permalink key allows for the definition of a custom URL structure for all documents within the collection. This provides clean, predictable, and SEO-friendly URLs. Variables like :path, :name, and :title can be used as placeholders.

collections:
 portfolio:
   output: true
   permalink: /projects/:title/

• Sorting Documents: By default, documents are sorted by date if available, or alphabetically otherwise. The sort_by key can be used to sort the collection based on a specific front matter key, which is invaluable for ordered content like tutorials or documentation chapters. For explicit manual ordering, the order key can be used with a list of filenames.

collections:
 tutorials:
   output: true
   sort_by: lesson_number

• Centralized Collection Directory: For large sites with numerous collections, the collections_dir key can be used to group all collection folders into a single parent directory, improving project organization. For example, setting collections_dir: content would mean Jekyll looks for a staff_members collection at content/_staff_members/.

2.2 Directory and Document Structure

Once a collection is defined in _config.yml, its content must be placed in a corresponding directory within the project’s root.

• The Underscore Convention: The content for a collection must reside in a folder that is prefixed with an underscore (_) and matches the collection’s label from the configuration file. For a collection named staff_members, the directory must be _staff_members/.
• The Document: Each item within a collection is represented by a file, typically a Markdown file with a .md extension. A key difference from posts is that collection documents have no mandatory filename convention. A file can be named jane-doe.md without any date prefix, leading to cleaner and more descriptive filenames.
• YAML Front Matter: For a file to be processed as a collection document, it must begin with a YAML front matter block, enclosed by triple-dashed lines (---). This block contains key-value pairs that define the document’s unique attributes and metadata, such as its title, layout, or any custom data like a team member’s job position or a project’s client name. If no front matter is present, Jekyll will not process the file as a collection document.

An example document for a staff_members collection might look like this:

_staff_members/jane-doe.md

---
name: "Jane Doe"
position: "Chief Executive Officer"
photo: "/assets/images/team/jane-doe.jpg"
layout: "staff_member_profile"
---
Jane Doe is the CEO and founder, with over 20 years of experience in the industry.

2.3 The Collection Data Flow: From File to Page

During the site build process, Jekyll executes a clear data pipeline for collections:

1. Configuration Reading: Jekyll first reads _config.yml to identify all defined collections.

Directory Parsing

2. Directory Parsing: It then scans the corresponding _collection_name directories for document files.
3. Data Processing: For each file containing YAML front matter, Jekyll parses the front matter data and the main content.
4. Global Availability: The parsed data for the entire collection is made globally available through the `site` Liquid variable. The collection can be accessed as an array of document objects using its label, for example, `site.staff_members`.

This global availability allows developers to access and display collection data on any page or layout using the Liquid templating language. A common pattern is to iterate through the collection’s array to generate lists, galleries, or navigation menus.

Code snippet

<h1>Our Team</h1>
<ul>
 {% for member in site.staff_members %}
   <li>
     <h2><a href="{{ member.url }}">{{ member.name }}</a></h2>
     <h3>{{ member.position }}</h3>
   </li>
 {% endfor %}
</ul>

Each document object in the array contains a rich set of attributes. These include all the custom key-value pairs defined in the document’s front matter (e.g., `member.name`, `member.position`) as well as several useful properties automatically generated by Jekyll, such as:

• member.url: The permalink of the generated page (only available if `output: true`).
• member.content: The rendered HTML content from the body of the Markdown file.
• member.path: The full path to the source file.
• member.collection: The label of the collection the document belongs to.

This robust data flow, from structured files on disk to a globally accessible array of objects, is what makes collections a powerful and flexible tool for content architecture in Jekyll.

Section 3: Comparative Analysis: Collections vs. Posts, Pages, and Data Files

To master collections, it is essential to understand not only what they are but also what they are not. A precise comparative analysis against Jekyll’s other content primitives—Posts, Pages, and Data Files—clarifies their unique architectural role and provides a clear framework for deciding which tool to use for a given content modeling task.

3.1 Collections vs. Posts: Breaking the Chronological Chains

The primary distinction between Collections and Posts lies in their relationship with time.

• Date Dependency: Posts are fundamentally date-driven. Their identity is tied to their publication date, which dictates their filename and their default reverse-chronological sorting order. They are designed for content where “when” it was published is a primary attribute. Collections, by contrast, are date-agnostic by default. While a document in a collection can have a date in its front matter, it is merely another piece of metadata and does not drive the core behavior or sorting unless explicitly configured to do so. Collections group content by shared purpose, not by time.
• Filename Convention: Posts enforce a strict `YYYY-MM-DD-title.markup` naming convention. Collections have no such requirement, allowing for cleaner, more semantic filenames like `project-gamma.md` or `api-authentication.md`.
• Directory Structure: All posts must reside in a single `_posts` directory. Collections allow for the creation of multiple, distinct content types, each in its own `_collection_name` directory at the root of the project. This enables a much more organized and scalable content architecture.
• Categorization: Posts have a built-in mechanism where subdirectories within `_posts` are automatically assigned as categories. Collections do not have this automatic behavior; if categorization is needed, it must be explicitly defined as a key in the document’s front matter.

3.2 Collections vs. Pages: Grouped vs. Standalone

While both Collections and Pages deal with non-chronological content, their fundamental difference is the relationship model.

• The Concept of a Group: The defining characteristic of a collection is that its documents form a cohesive, related group. A `_recipes` collection implies that every document within it is a recipe. Pages, conversely, are designed to be standalone and unrelated. An `about.md` page and a `contact.md` page share no intrinsic link other than being part of the same website.
• Iterability: Because collections are defined as a group, Jekyll makes them easily iterable via the `site` variable (e.g., `site.recipes`). This makes generating index pages, lists, and navigation straightforward. There is no simple, built-in mechanism to iterate over a subset of Pages that are conceptually related, as they lack this inherent group identity.
• Architectural Impact: Attempting to manage a set of related items like a project portfolio using only Pages would be architecturally unsound. It would require manual lists or complex front matter logic to create relationships between them. Collections provide a native, clean, and scalable data source for such content, making the overall site architecture more robust and maintainable.

3.3 Collections vs. Data Files: Content vs. Data

Collections and Data Files (`_data/`) both allow for structured data to be used throughout a site, but they serve distinct purposes, and the choice between them hinges on one critical question.

• Individual Page Output: This is the most significant differentiator. Data files, stored in formats like YAML or JSON in the `_data` directory, are purely for storing structured data. They can never generate their own pages. A `_data/authors.yml` file can provide author metadata to be displayed on post pages, but there can never be a dedicated `/authors/jane-doe/` page generated from it. Collections, when configured with `output: true`, are specifically designed to generate an individual page for each document.
• Content Body: Collection documents support a full Markdown content body, which is rendered and made available via the `{{ content }}` variable. This makes them ideal for long-form prose, such as an author’s biography, a detailed project description, or a documentation article. Data files are best suited for key-value pairs or simple lists and are unwieldy for managing large blocks of formatted text.
• The Deciding Question: The choice between a collection and a data file can be simplified to a single question: “Does each item in this set need its own dedicated URL and page?” If the answer is yes, a collection is the correct tool. If the answer is no, and the information is purely supplemental data to be used on other pages, a data file is the more appropriate and efficient choice.

3.4 Jekyll Content Primitives: A Comparative Matrix

The following table provides a consolidated, at-a-glance comparison of Jekyll’s four primary content primitives, serving as a decision-making tool for content architecture.

Feature	Posts	Pages	Collections	Data Files
Primary Purpose	Chronological articles, blog entries	Standalone, static content	Grouped, related, non-chronological content	Site-wide structured data
Directory	_posts/	Any directory (not prefixed with _)	_collection_name/	_data/
Filename Convention	YYYY-MM-DD-title.markup (Strict)	Any (Flexible)	Any (Flexible)	filename.yml, .json, etc.
Date-Awareness	High (Drives sorting and identity)	Low (Metadata only)	Low (Metadata only, unless sort_by is used)	Not Applicable
Grouping	Implicitly grouped by date	Ungrouped, standalone	Explicitly grouped by collection	Grouped by filename
Individual Page Output	Yes (Always)	Yes (Always)	Optional (via output: true)	No (Never)
Data Access (Liquid)	site.posts	site.pages	site.collection_name	site.data.filename
Canonical Use Case	Blog articles, news updates	About page, contact form	Team members, portfolio, documentation	Author metadata, site settings

Section 4: Practical Implementation and Common Use Cases

Transitioning from theory to practice reveals the true power and flexibility of Jekyll Collections. The following detailed examples demonstrate how to implement collections to solve common content architecture challenges, from building a project portfolio to creating a relational link between authors and their articles.

Setup

First, define the portfolio collection in _config.yml, enabling page output and specifying a clean permalink structure.

YAML

# _config.yml
collections:
 portfolio:
   output: true
   permalink: /portfolio/:title/

Content

Next, create a _portfolio/ directory. Inside, each project is a separate Markdown file. The front matter holds structured data like the project title, client, and a cover image, while the body contains the detailed project description.

_portfolio/project-alpha.md

---
title: "Project Alpha"
client: "Global Tech Inc."
cover_image: "/assets/images/portfolio/alpha-cover.jpg"
tags:
---

Project Alpha was a complete overhaul of the client's customer-facing portal...

Listing Page

Create a portfolio.html page to display a gallery of all projects.

This page iterates through site.portfolio to build a visual grid, with each item linking to its unique project URL.

Code snippet

---
layout: default
title: Our Portfolio
---
<h1>Our Work</h1>
<div class="portfolio-grid">
 {% for project in site.portfolio %}
   <div class="portfolio-item">
     <a href="{{ project.url | relative_url }}">
       <img src="{{ project.cover_image | relative_url }}" alt="{{ project.title }}">
       <h2>{{ project.title }}</h2>
       <p>{{ project.client }}</p>
     </a>
   </div>
 {% endfor %}
</div>

Detail Page

Finally, create a layout file at _layouts/portfolio_item.html to render the individual project pages. This layout uses Liquid variables to display the project’s specific front matter and its full content body. The layout for each project document can be set in its front matter or, more efficiently, using Front Matter Defaults (covered in Section 5).

Code snippet

---
layout: default
---
<article>
 <h1>{{ page.title }}</h1>
 <p><strong>Client:</strong> {{ page.client }}</p>
 <img src="{{ page.cover_image | relative_url }}" alt="{{ page.title }}">
 
 <div class="project-content">
   {{ content }}
 </div>
</article>

4.2 Use Case: The Documentation Hub

Collections are exceptionally well-suited for building structured documentation sites, where content must be organized into logical sections and presented in a specific order.

Setup

Define multiple collections in _config.yml to represent different sections of the documentation. Using sort_by is critical here to enforce a logical reading order.

YAML

# _config.yml
collections:
 getting_started:
   output: true
   sort_by: order
 api_reference:
   output: true
   sort_by: order

Content

Populate the _getting_started/ and _api_reference/ directories with documents. Each document should include an order key in its front matter to control its position within the section.

_getting_started/01-installation.md

________________
title: "Installation" order: 1
To install our software, you will first need to...

Navigation

A dynamic sidebar navigation can be constructed in a layout or include file by iterating through each documentation collection. This ensures the navigation is always up-to-date and reflects the specified order.

Code snippet

<nav>
 <h3>Getting Started</h3>
 <ul>
   {% for doc in site.getting_started %}
     <li><a href="{{ doc.url | relative_url }}">{{ doc.title }}</a></li>
   {% endfor %}
 </ul>

 <h3>API Reference</h3>
 <ul>
   {% for doc in site.api_reference %}
     <li><a href="{{ doc.url | relative_url }}">{{ doc.title }}</a></li>
   {% endfor %}
 </ul>
</nav>

4.3 Use Case: The Team Directory and Relational Content

This use case demonstrates one of the most powerful aspects of collections: their ability to create relational data models within a static site. Here, we will create a collection of authors and link them to their respective blog posts.

Setup

First, configure an authors collection, ensuring output: true so each author can have a profile page.

YAML

# _config.yml
collections:
 authors:
   output: true

Content

Create an _authors/ directory. Each author file contains their details. A unique identifier, like username, is essential for creating the link.

_authors/jill-smith.md

________________
name: "Jill Smith" username: "jill" position: "Lead Developer" avatar: "/assets/images/team/jill.jpg"
Jill is the lead developer, specializing in front-end technologies...

Linking Posts to Authors

In the front matter of a standard Jekyll post, add an author key that matches the username of an author in the collection. This simple string acts as a “foreign key.”

_posts/2023-10-27-new-feature-launch.md

________________
layout: post title: "Announcing Our New Feature" author: "jill"
Today we are excited to launch...

Displaying Author Information

In the post layout (_layouts/post.html), use Liquid to perform a lookup. The code iterates through the site.authors collection to find the document whose username matches the post’s author value. Once found, it can display the author’s information.

Code snippet

...
<article>
 <h1>{{ page.title }}</h1>

 {% assign author = site.authors | where: "username", page.author | first %}
 {% if author %}
   <div class="author-box">
     <img src="{{ author.avatar | relative_url }}" alt="{{ author.name }}">
     <div>
       <strong>By <a href="{{ author.url | relative_url }}">{{ author.name }}</a></strong>
       <p>{{ author.position }}</p>
     </div>
   </div>
 {% endif %}

 {{ content }}
</article>
...

This final step is more than just displaying data; it demonstrates a profound capability. The system is executing a query-like operation at build time, establishing a one-to-many relationship (one author can have many posts) between two distinct content types. This is the foundation of a relational data model, implemented entirely within Jekyll’s static site generation process. This technique unlocks the ability to build complex, interconnected content networks—such as events linked to venues, products linked to categories, or publications linked to researchers—without the need for a server-side database. It is this relational power that elevates collections from simple content containers to a sophisticated architectural tool.

Section 5: Advanced Collection Management and Architecture

For developers building large, complex, or highly customized Jekyll sites, mastering advanced collection features is essential for maintaining scalability, consistency, and efficiency. These techniques focus on URL design, content management, and extending native functionality.

5.1 Mastering Permalinks and URL Structures

Jekyll provides a set of special variables specifically for constructing permalinks within a collection’s configuration, offering fine-grained control over the final URL structure.

• :collection: The label of the collection (e.g., portfolio).
• :path: The full path to the document relative to the collection’s directory, including any subdirectories.
• :name: The document’s base filename without the extension.
• :title: The document’s title from its front matter, “slugified” for URL safety.

By combining these variables, architects can design logical and future-proof URL schemes. For a documentation site, a path-based URL might be ideal to reflect the content’s hierarchy:

YAML

collections:
 docs:
   output: true
   permalink: /documentation/:path/

A document at _docs/getting-started/installation.md would then render at /documentation/getting-started/installation/.

For a team directory, a simpler, title-based URL is more appropriate:

YAML

collections:
 team:
   output: true
   permalink: /team/:title/

A document at _team/jane-doe.md with title: Jane Doe would render at /team/jane-doe/. Strategic URL design improves user experience, SEO, and the overall logical structure of the site.

5.2 Leveraging Front Matter Defaults for DRY Content

On large sites, repeating the same front matter keys—such as layout or author_profile—in every document of a collection is tedious, error-prone, and violates the “Don’t Repeat Yourself” (DRY) principle. Jekyll’s defaults configuration key provides an elegant solution by allowing you to set default front matter values scoped to a specific path or content type.

By specifying a scope with a type matching the collection’s label, you can apply a set of values to every document within that collection automatically.

YAML

# _config.yml
collections:
 docs:
   output: true
 portfolio:
   output: true

defaults:
 - scope:
     path: ""
     type: "docs"
   values:
     layout: "documentation"
     sidebar: "docs_nav"
 - scope:
     path: ""
     type: "portfolio"
   values:
     layout: "portfolio_item"
     show_share_buttons: true

With this configuration, any document inside _docs/ will automatically have its layout set to documentation without needing layout: documentation in its front matter. This centralizes configuration, ensures consistency, and simplifies content creation.

This mechanism, especially when combined with collections_dir, creates a powerful “Convention over Configuration” framework. An architect can pre-define the entire structure and behavior for different content types. A content creator’s task is then simplified to placing a new Markdown file in the correct directory; the system automatically applies the correct layout, metadata, and structural rules. This mirrors the efficient workflows of mature software development frameworks, reducing cognitive overhead and enabling content operations to scale effectively.

5.3 Extending Functionality with Plugins

While collections are powerful, they have some native limitations. One historical gap was that Jekyll’s built-in pagination only worked for posts. The Jekyll ecosystem, however, offers a rich variety of plugins to extend this functionality.

• Pagination for Collections: Modern plugins like jekyll-paginate-v2 have been developed to fill this gap, offering robust pagination that works seamlessly with collections, pages, and tags.
• Category and Tag Archives: Plugins like jekyll-collection-pages can automatically generate index pages for metadata within a collection.

For example, it can create a unique page for every tag used across all documents in a portfolio collection, effectively building tag archive pages without manual effort. This allows for the creation of rich, faceted navigation systems for your structured content.

5.4 Architectural Patterns for Large-Scale Sites

As sites grow in complexity, advanced architectural patterns become necessary to manage content relationships and maintainability.

• Inter-Collection Relationships: The author-to-post relationship (one-to-many) can be extended. To model a many-to-many relationship—for example, between a talks collection and a speakers collection where a talk can have multiple speakers and a speaker can give multiple talks—you can use an array in the front matter.

  _talks/keynote-address.md

  title: “The Future of Static Sites”
  speakers: [jane-doe, john-smith]

  The templates can then loop through this array to find and display each associated speaker, and a speaker’s page can perform a reverse lookup to find all talks they are associated with.

• Collections as “Content Snippets”: A collection with output: false serves as an excellent tool for managing reusable blocks of content that are more complex than what a data file can handle. For instance, a _testimonials collection could hold customer quotes, each with a name, company, photo, and a full Markdown paragraph for the testimonial itself. These can then be pulled into various pages across the site as needed, providing a single source of truth for this content that is easy for non-developers to edit.
• Scalability and Maintenance: For projects with dozens of collections, organization is paramount. Using the collections_dir setting to group all collection folders under a single parent directory (e.g., _content/) is a crucial first step. Adopting a clear and consistent naming strategy for both collections and their front matter keys prevents confusion and ensures the project remains maintainable as it scales.

Conclusion

Jekyll Collections represent a fundamental architectural evolution, transforming the platform from a specialized blogging engine into a versatile, general-purpose static site generator. They are the official and most robust solution for managing groups of related, non-chronological content, filling a critical gap left by the traditional Post and Page primitives.

The analysis reveals that the core strength of collections lies in their ability to impose structure and relationships on content. The decision to use a collection hinges on a clear understanding of its place within Jekyll’s content model:

• Use Posts for time-sensitive, chronological content like blog articles.
• Use Pages for standalone, unrelated content like an “About Us” page.
• Use Data Files for simple, structured key-value data that does not require its own page or long-form content.
• Use Collections when content is part of a thematically related group, requires its own page and URL, and benefits from a structured, iterable format.

Beyond simple grouping, collections unlock advanced, CMS-like capabilities. Their ability to form relational links between different content types—as demonstrated by connecting authors to posts—enables the creation of sophisticated, interconnected data models without the overhead of a dynamic backend. When combined with advanced features like Front Matter Defaults and a rich ecosystem of plugins, collections provide the foundation for building large-scale, maintainable, and architecturally sound static websites.

Ultimately, mastering collections is synonymous with mastering modern Jekyll. For developers, technical writers, and content strategists, a deep understanding of this powerful feature is the key to unlocking the full potential of static site generation for complex and data-rich projects.