Jekyll Data Files: Master YAML, JSON, CSV for Dynamic Content

I. Architectural Principles of Data-Driven Content in Jekyll

Jekyll’s data files represent a fundamental architectural pattern that elevates a static site from a collection of hard-coded pages to a dynamic, maintainable, and scalable system. By providing a mechanism to separate structured content from its presentation, data files introduce a paradigm that mirrors the functionality of a traditional database, enabling sophisticated content management workflows within a static generation context.

1.1 Decoupling Data from Presentation: The “Mini-Database” Paradigm

The core principle behind Jekyll’s data file feature is the decoupling of content (the data) from its presentation layer (the template). Jekyll allows developers to define custom, structured data in dedicated files, which can then be accessed globally throughout the site using the Liquid templating language. This functionality effectively serves as a substitute for a dynamic database or an external API, providing a “mini-database” directly within the project’s source code.

This separation is a powerful architectural advantage. By isolating data—such as a list of team members, frequently asked questions, or product specifications—into centralized files, developers can eliminate redundant content embedded within HTML templates. For example, a single _data/team.yml file can serve as the canonical source for all staff information. This data can then be rendered in multiple contexts across the site: as a detailed profile grid on an “About Us” page, as a simple dropdown list in a contact form, or as an author byline on a blog post. If a team member’s title changes, the update needs to be made in only one place, and the change will propagate across the entire site upon the next build. This dramatically improves site maintainability and reduces the potential for inconsistencies.

This architectural decoupling also has profound implications for team collaboration and content workflows. The data files, typically written in human-readable formats like YAML or CSV, are significantly more accessible to non-technical contributors than the complex Liquid and HTML logic found in templates. This creates a natural separation of concerns:

• Developers and Designers focus on the site’s structure, logic, and styling by managing files in the _layouts and _includes directories.
• Content Managers, Marketers, and Subject Matter Experts can be empowered to update, add, or remove content by directly editing the straightforward data files in the _data directory.

This workflow minimizes the risk of a content update inadvertently breaking the site’s layout or functionality. It transforms Jekyll from a tool solely for developers into a more inclusive, collaborative platform. This approach is a foundational step toward a Git-based headless Content Management System (CMS) architecture, where the _data directory acts as a version-controlled content repository and the Jekyll build process serves as the presentation layer, or “head.”

1.2 The Role and Mechanics of the _data Directory

Jekyll’s data handling is governed by a simple but powerful convention: it automatically locates and processes data files stored within a special directory named _data at the root of the project. This is a “convention-over-configuration” feature, meaning it works out of the box without requiring any explicit setup in the main _config.yml file. This low barrier to entry distinguishes data files from other Jekyll features like Collections, which must be explicitly defined in the configuration file before they can be used.

It is critical, however, to understand the architectural role of the _data directory. Its contents are designed to be supplemental data used to enrich pages, posts, and layouts. Unlike posts in the _posts directory or documents within a configured collection, items in a data file do not, by default, generate their own individual pages. For instance, if you have a _data/products.yml file with 50 products, Jekyll will not automatically create 50 unique product detail pages. Instead, the data is loaded into memory and made available for rendering within other pages, such as a main product listing page.

To generate a unique, standalone page for each record in a data file, a Jekyll plugin is required. This reveals a core design boundary within Jekyll: the _data directory is intended for structured information that supports existing content, not as the primary source for page generation itself. This distinction is vital for architects planning a new Jekyll site. If a primary requirement is to generate a large number of individual pages from a dataset, relying solely on Jekyll’s native data file feature will be insufficient. In such cases, developers must either leverage a plugin like jekyll-datapage_gen or evaluate whether another static site generator with more robust data-to-page generation capabilities would be a better fit for the project.

1.3 How Jekyll Processes and Exposes Data via the site.data Global Variable

During the site build process, Jekyll reads all valid files from the _data directory and its subdirectories. It supports several data formats, including YAML (.yml, .yaml), JSON (.json), CSV (.csv), and TSV (.tsv). The parsed content of these files is loaded into a single, globally accessible Liquid object: site.data.

The structure of the site.data object is determined by the filenames within the _data directory. The basename of each file (the name without the extension) becomes a key on the site.data object. For example:

• A file named _data/members.yml will be accessible via site.data.members.
• A file named _data/social_links.json will be accessible via site.data.social_links.
• A file named _data/pricing.csv will be accessible via site.data.pricing.

Because this data is loaded into a global variable, it can be accessed from any file that Jekyll processes with Liquid, including pages, posts, layouts, and includes. This makes it exceptionally well-suited for site-wide elements like navigation menus, footer information, social media links, or configuration variables that need to be referenced across multiple templates.

A crucial technical consideration is that the file’s basename is the sole determinant of the variable name. Therefore, developers should avoid placing files with the same basename but different extensions in the same directory (e.g., _data/members.yml and _data/members.json). In such a case, one file’s data is likely to overwrite the other’s during the build process, leading to unpredictable results.

II. Comparative Analysis of Data Formats: YAML, JSON, and CSV

Jekyll’s flexibility in supporting multiple data formats is a significant advantage, as it allows developers to choose the most appropriate format for the specific type of data and the intended workflow. The choice between YAML, JSON, and CSV is not merely a matter of syntax but a strategic decision that impacts readability, maintainability, and interoperability.

2.1 YAML (YAML Ain’t Markup Language)

YAML is a human-readable data serialization format that relies on indentation and whitespace to define its structure, eschewing the brackets and braces common in other formats. It is a superset of JSON and is particularly prevalent within the Ruby ecosystem, making it a natural fit for Jekyll. YAML supports key-value pairs (mappings), lists (sequences), and complex, deeply nested data structures.

For Jekyll projects, YAML is often the default and most versatile choice for data that is manually created and maintained. Its clean, minimal syntax makes it exceptionally readable, which is ideal for content-rich data like navigation menus with nested sub-items, service descriptions with lists of features, or detailed author profiles.

A key characteristic of YAML is its sensitivity to whitespace. Each new level of nesting is typically defined by a two-space indent. While this contributes to its clean appearance, it can also be a common source of build errors if indentation is inconsistent or if tabs are used instead of spaces. This is a critical practical consideration for teams, who should establish clear coding standards and configure their text editors to ensure consistent whitespace handling.

2.2 JSON (JavaScript Object Notation)

JSON is a lightweight, text-based data-interchange format that is easy for machines to parse and generate. Its syntax is stricter than YAML‘s, using curly braces {} to define objects (key-value maps) and square brackets [] for arrays (lists).

JSON‘s primary strength is its ubiquity and role as the de facto standard for web APIs and client-side JavaScript. Within a Jekyll project, JSON is the ideal format when the data is being consumed from an external API or when it is intended to be passed directly to a client-side JavaScript application. A common use case is populating an interactive map library (like Google Maps or Leaflet.js) with location data stored in a .json file.

When using data from any source file (including a .json file) in a client-side script, a specific Liquid filter is essential. Jekyll parses all data files into internal Ruby objects (hashes and arrays). If this Ruby object is output directly into a <script> tag (e.g., let data = {{ site.data.locations }};), the resulting string will be the Ruby object’s representation, which is not valid JSON and will cause a JavaScript error. To solve this, developers must use the jsonify filter: let data = {{ site.data.locations | jsonify }};. This filter explicitly converts the Ruby object back into a correctly formatted, valid JSON string that can be safely parsed by JavaScript.

“`html

This is a crucial and often misunderstood step for integrating Jekyll data with client-side logic.

2.3 CSV (Comma-Separated Values)

CSV is a simple, text-based format for representing tabular data. Each line in a CSV file corresponds to a row in a table, and commas separate the values within that row. Jekyll can process CSV files stored in the _data directory, with one important requirement: the file must contain a header row.

This header row is the key to CSV’s power within Jekyll. Jekyll uses the values in the first row as the keys for each subsequent row’s data. This transforms each row from a simple array of values into a structured object, much like an entry in a YAML or JSON file. For example, given a _data/members.csv file:

name,github_username,role
Alice Smith,alices,Developer
Bob Johnson,bobj,Designer

Jekyll will parse this into an array of objects. In Liquid, one can then access the data for each member using dot notation (e.g., member.name, member.github_username), making the templating syntax identical to that used for other data formats.

CSV is the most efficient format for managing flat, non-hierarchical data. Its primary advantage is its accessibility to non-technical users, as CSV files can be easily created and edited using common spreadsheet applications like Microsoft Excel or Google Sheets. This makes it an excellent choice for managing simple lists of team members, product inventories, event schedules, or URL redirect mappings.

2.4 Data Format Comparison Matrix

The following table provides a comparative summary to guide the selection of the appropriate data format for various use cases within a Jekyll project.

III. Core Implementation: Rendering Data with Liquid

Once data is stored in the _data directory, Jekyll’s templating language, Liquid, provides the tools to access, iterate over, and conditionally display that information within any page, post, or layout. Mastering these core Liquid constructs is essential for unlocking the full potential of data-driven content.

3.1 Accessing Data: The site.data Object and Dot/Bracket Notation

All data loaded from the _data directory is available through the global site.data object. Data can be accessed using standard dot notation, chaining keys to traverse the data structure. For example, to access the name of the first member in a _data/team.yml file, the syntax would be {{ site.data.team.name }}. While dot notation is common for direct access, Liquid also supports bracket notation, which is essential for dynamic access where the key is stored in another variable. This is a particularly powerful technique for cross-referencing information. For instance, a common pattern is to define a list of authors in _data/authors.yml, where each author has a unique identifier (e.g., jsmith). A blog post’s front matter can then reference this author using author: jsmith. In the post layout, bracket notation can be used to retrieve the full author profile:

{% raw %}
{% assign author_id = page.author %}
{% assign author_profile = site.data.authors[author_id] %}

<div class="author-bio">
 <img src="{{ author_profile.avatar }}" alt="{{ author_profile.name }}">
 <h3>{{ author_profile.name }}</h3>
 <p>{{ author_profile.bio }}</p>
</div>
{% endraw %}

In this example, site.data.authors[author_id] dynamically looks up the author profile using the author_id variable, a feat not possible with dot notation.

3.2 Iterating Over Data Collections: Mastering the for Loop

The primary mechanism for rendering lists of data is the Liquid {% for %} loop. This tag iterates over an array—such as the list of members from a members.yml file—and makes each item available as a temporary variable within the loop block.

A basic loop to render a list of team members would look like this:

{% raw %}
<div class="team-grid">
 {% for member in site.data.members %}
   <div class="team-member-card">
     <img src="{{ member.image_url }}" alt="Photo of {{ member.name }}">
     <h4>{{ member.name }}</h4>
     <p>{{ member.title }}</p>
   </div>
 {% endfor %}
</div>
{% endraw %}

This loop iterates through each object in the site.data.members array, assigning the current object to the member variable for each iteration.

Liquid also provides a special forloop object inside every for loop, which contains helpful properties about the iteration state:

• forloop.index: The current iteration of the loop (1-indexed).
• forloop.index0: The current iteration of the loop (0-indexed).
• forloop.first: Returns true if it is the first iteration.
• forloop.last: Returns true if it is the last iteration.
• forloop.length: The total number of items in the collection.

These helpers are useful for applying conditional logic or styling. For example, one could add a divider between list items but not after the last one:

{% raw %}
{% for item in site.data.navigation %}
 <a href="{{ item.url }}">{{ item.name }}</a>
 {% unless forloop.last %} | {% endunless %}
{% endfor %}
{% endraw %}

3.3 Conditional Logic with Data

Liquid’s control flow tags, such as {% if %}, {% else %}, {% elsif %}, and {% unless %}, allow for the conditional rendering of content based on the values within data files. This is fundamental for creating dynamic and responsive templates.

A common use case is highlighting the currently active page in a navigation menu. By comparing the current page’s URL (page.url) with the link from the navigation data file, a special CSS class can be applied:

{% raw %}
<nav>
 {% for item in site.data.navigation %}
   <a href="{{ item.link }}" {% if page.url == item.link %}class="active"{% endif %}>
     {{ item.name }}
   </a>
 {% endfor %}
</nav>
{% endraw %}

This technique provides clear visual feedback to the user about their location on the site.

Conditional logic can also be used to filter or customize the display of data. For example, a “Featured” badge could be shown next to a service only if a corresponding boolean flag is set to true in the data file:

{% raw %}
{% for service in site.data.services %}
 <h4>
   {{ service.name }}
   {% if service.featured == true %}
     <span class="badge">Featured</span>
   {% endif %}
 </h4>
{% endfor %}
{% endraw %}

3.4 Essential Liquid Filters for Data Manipulation

Liquid filters are simple methods that modify the output of strings, numbers, variables, and objects. They are placed within an output tag {{ }} and are separated from the variable by a pipe character |. Several filters are particularly useful when working with data files.

• size: Returns the number of items in an array or characters in a string. It is useful for displaying counts, such as the number of members in an organization: {{ org.members | size }} members.
• jsonify: As discussed previously, this filter converts a Liquid object (a Ruby hash or array) into a valid JSON string, which is essential for safely passing data to client-side JavaScript.
• sort: Sorts an array of objects by a given property. This is useful for ensuring that lists are displayed in a consistent order, such as alphabetizing a list of team members: {% for member in site.data.team | sort: 'name' %}.
• where: Filters an array of objects to return only the items where a specific property matches a given value. This is an extremely powerful filter for creating specialized views of data without complex if logic inside a loop. For example, to create a list of only the developers on a team: {% assign developers = site.data.team | where: "role", "Developer" %}.
• group_by: Groups an array of objects by a given property. This is useful for creating sectioned lists, such as grouping products by their category.

These filters provide powerful, declarative ways to manipulate data directly within templates, keeping the logic clean and readable.

IV. Practical Applications and Case Studies

The following case studies demonstrate how to apply the principles of data files and Liquid templating to build common website components. Each example provides the data structure in multiple formats and the corresponding Liquid code for rendering.

4.1 Case Study 1: Building a Team Members Page

This example creates a responsive grid of team member profiles, sourcing the content from a data file.

“`

This approach allows for easy updates to staff information without touching any HTML.

Data Files

The data for each team member includes their name, title, a short biography, an image URL, and a nested list of social media links.

_data/team.yml (YAML)

YAML

- name: "Dr. Eleanor Vance"
  title: "Lead Researcher"
  bio: "Eleanor specializes in quantum computing and has published over 50 papers on the subject."
  image_url: "/assets/images/eleanor.jpg"
  social_links:
    - platform: "Twitter"
      url: "https://twitter.com/example"
    - platform: "LinkedIn"
      url: "https://linkedin.com/in/example"
- name: "Marcus Holloway"
  title: "Senior Developer"
  bio: "Marcus is a full-stack developer with a passion for open-source software and elegant code."
  image_url: "/assets/images/marcus.jpg"
  social_links:
    - platform: "GitHub"
      url: "https://github.com/example"

_data/team.json (JSON)

JSON

  },
{
  "name": "Marcus Holloway",
  "title": "Senior Developer",
  "bio": "Marcus is a full-stack developer with a passion for open-source software and elegant code.",
  "image_url": "/assets/images/marcus.jpg",
  "social_links": [
    { "platform": "GitHub", "url": "https://github.com/example" }
  ]
}
]

_data/team.csv (CSV)

Note: CSV cannot easily represent nested data like social_links. For this format, social links are simplified into separate columns.

Code snippet

name,title,bio,image_url,twitter_url,linkedin_url,github_url
"Dr. Eleanor Vance","Lead Researcher","Eleanor specializes in quantum computing...","/assets/images/eleanor.jpg","https://twitter.com/example","https://linkedin.com/in/example",
"Marcus Holloway","Senior Developer","Marcus is a full-stack developer...","/assets/images/marcus.jpg",,,"https://github.com/example"

Liquid Template

This template iterates through the site.data.team object (assuming the YAML or JSON file is used) and generates an HTML card for each member. It includes a nested loop for social links and a conditional check to display the bio only if it exists.

HTML

{% raw %}
Our Team

  {% for member in site.data.team %}
    

      
      

        
{{ member.name }}
        
{{ member.title }}
        {% if member.bio %}
          
{{ member.bio }}
        {% endif %}
        {% if member.social_links %}
          

            {% for social in member.social_links %}
              {{ social.platform }}
            {% endfor %}
          
        {% endif %}
      
    
  {% endfor %}

{% endraw %}

Case Study 2: Creating a Dynamic FAQ Section

This example uses a YAML data file to manage a list of frequently asked questions and their answers, rendering them as an HTML accordion. This pattern is ideal for keeping content organized and easily updatable.

Data File (_data/faqs.yml)

The data is structured as a simple list of objects, where each object contains a question and an answer. The answer can contain Markdown for formatting.

YAML

- question: "What is a static site generator?"
  answer: "A static site generator, like Jekyll, is a tool that builds a complete website as static HTML, CSS, and JavaScript files. Unlike a dynamic CMS like WordPress, it does not require a database or server-side processing at request time, which makes the resulting site very fast and secure."
- question: "Do I need to know Ruby to use Jekyll?"
  answer: "No, you do not need to be a Ruby programmer to use Jekyll. You only need to have Ruby and the Jekyll gem installed on your machine to run the build commands. Most site development is done using HTML, CSS, Markdown, and Liquid."
- question: "Where can I host a Jekyll site?"
  answer: "Jekyll sites can be hosted on any standard web server since they consist of static files. They are particularly well-suited for services like GitHub Pages, Netlify, and Vercel, which offer seamless deployment from a Git repository."

Liquid Template

The template loops through site.data.faqs and generates the HTML structure for an accordion. The markdownify filter is used to process any Markdown in the answer field, allowing for rich text formatting like links and lists.

HTML

{% raw %}
Frequently Asked Questions

  {% for item in site.data.faqs %}
    

      {{ item.question }}
      

        {{ item.answer | markdownify }}
      
    
  {% endfor %}



{% endraw %}

Case Study 3: Managing a List of Services

This example demonstrates a more advanced use of Liquid to display a list of company services. It uses the where filter to create a separate, prominent section for “featured” services before listing all services.

Data File (_data/services.yml)

Each service has a name, description, a list of key features, and a boolean featured flag.

YAML

- name: "Web Development"
  description: "Building fast, secure, and scalable websites using modern technologies."
  features:
    - "Static Site Generation with Jekyll"
    - "Headless CMS Integration"
    - "Performance Optimization"
  featured: true
- name: "Content Strategy"
  description: "Developing a comprehensive content plan to meet your business goals."
  features:
    - "Audience Research"
    - "SEO Keyword Analysis"
    - "Editorial Calendar Planning"
  featured: false
- name: "API Integration"
  description: "Connecting your website to third-party services and data sources."
  features:
    - "REST & GraphQL APIs"
    - "Payment Gateway Integration"
    - "Custom Data Synchronization"
  featured: true

Liquid Template

The template first uses the where filter to create a new array containing only the featured services. It loops through this new array to create the “Featured Services” section. Afterwards, it loops through the original, complete list of services to display all offerings.

HTML

{% raw %}
{% assign featured_services = site.data.services | where: "featured", true %}
{% if featured_services.size > 0 %}
  

    
Featured Services
    

      {% for service in featured_services %}
        

          
{{ service.name }}
          
{{ service.description }}
        
      {% endfor %}
    
  
{% endif %}


  
All Our Services
  {% for service in site.data.services %}
    

      
{{ service.name }}
      
{{ service.description }}
      

        {% for feature in service.features %}
          
{{ feature }}
        {% endfor %}
      
    
  {% endfor %}

{% endraw %}

Advanced Techniques and Scalability

As a Jekyll site grows in size and complexity, managing data effectively becomes crucial for maintaining performance and organization. Advanced techniques involving directory structure, data cross-referencing, and custom parsing can help scale a project gracefully.

Namespacing and Organization: Using Subdirectories

For large websites, placing dozens of data files in the root of the _data directory can quickly become disorganized. Jekyll addresses this by supporting subdirectories within _data. Each folder level adds a new level of namespacing to the site.data object, allowing for a logical, hierarchical organization of data.

For example, a site’s data could be structured as follows:

_data/
├── social/
│   ├── links.yml
│   └── icons.yml
├── navigation/
│   ├── main.yml
│   └── footer.yml
└── members.yml

This data would be accessed in Liquid using a namespaced path:

• site.data.social.links
• site.data.navigation.main
• site.data.members

This namespacing strategy is an essential technique for scalability. It prevents filename collisions, groups related data together, and makes the project’s data architecture self-documenting and easier for new developers to understand.

Cross-Referencing Data Between Files

One of the most powerful advanced techniques is to establish relationships between different data sources. This allows for the creation of a relational-like data model, reducing duplication and centralizing information. The most common pattern involves defining a canonical data set in one file and referencing it from another, typically from a page or post’s front matter.

Consider a scenario with blog posts written by multiple authors.

“`html

Instead of repeating author information in the front matter of every post, a centralized _data/authors.yml file can store detailed profiles:

sylhare:
  name: "Sylhare"
  avatar: "/assets/img/avatars/sylhare.png"
  url: "https://github.com/sylhare"
  bio: "Expert in Jekyll and static site architecture."

jdoe:
  name: "Jane Doe"
  avatar: "/assets/img/avatars/jdoe.png"
  url: "https://example.com/jdoe"
  bio: "Specialist in content strategy and digital marketing."

A blog post can then simply reference the author by their unique key:

title: "Advanced Jekyll Techniques"
layout: post
author: sylhare

Content of the post...

In the post layout, this reference is used to look up the full author profile from the data file using bracket notation:

{% raw %}
{% if page.author %}
  {% assign author_data = site.data.authors[page.author] %}
  <div class="author-box">
    <img src="{{ author_data.avatar }}" alt="Avatar for {{ author_data.name }}">
    <div>
      Written by <a href="{{ author_data.url }}">{{ author_data.name }}</a>
      <p>{{ author_data.bio }}</p>
    </div>
  </div>
{% endif %}
{% endraw %}

This approach ensures that author information is managed in a single place, adhering to the “Don’t Repeat Yourself” (DRY) principle. However, it is important to recognize the limits of Jekyll’s native data-referencing capabilities. While this key-based lookup works exceptionally well, more complex data composition is not supported out of the box. For instance, YAML’s native anchor (&) and alias (*) features, which allow for reusing data snippets, only function within the scope of a single file. Jekyll does not process Liquid tags like {% include %} inside data files during its initial data-loading phase, meaning one YAML file cannot natively include another to share common values. To achieve this level of advanced data composition, developers must resort to custom Jekyll plugins that preprocess data files with Liquid. This adds a layer of complexity and can create compatibility issues with restricted build environments like the default GitHub Pages service.

5.3 Customizing Data Parsing: _config.yml for CSVs

For projects that rely heavily on CSV data, Jekyll provides a way to customize how these files are parsed. In the _config.yml file, the csv_reader key can be used to specify options for Ruby’s CSV library.

The most useful options are:

• converters: An array of converters to apply to the data. For example, using numeric will automatically convert columns containing numbers into integer or float types instead of leaving them as strings. Other options include integer, float, date, and date_time.
• headers: A boolean that defaults to true. Setting it to false would treat the first row as data rather than as headers.
• encoding: Specifies the file encoding, such as utf-8.

Example _config.yml configuration:

csv_reader:
  converters:
    - numeric
    - date_time
  encoding: "utf-8"

Using converters can significantly simplify Liquid templates by ensuring data is in the correct format from the start, avoiding the need for filters to manually cast types (e.g., | plus: 0 to convert a string to a number).

5.4 Table: Advanced Liquid Techniques for Data Files

This table summarizes advanced Liquid patterns for manipulating data from the _data directory, serving as a quick reference for developers.

VI. Conclusion

Jekyll’s data files are a cornerstone feature that enables the creation of complex, maintainable, and scalable static websites. By embracing the architectural principle of decoupling data from presentation, developers can build systems that are not only efficient to manage but also foster better collaboration between technical and non-technical team members. The _data directory, when used effectively, transforms from a simple folder into a structured, site-wide “mini-database” that powers dynamic components, from navigation menus to detailed content listings.

The choice of data format—YAML, JSON, or CSV—is a strategic one, guided by the specific requirements of the data’s structure, its intended use, and the workflows of the team managing it. YAML excels in human-edited, hierarchical content; JSON is the standard for interoperability with APIs and JavaScript; and CSV offers unparalleled accessibility for simple, tabular data managed in spreadsheets.

Mastering the core Liquid constructs for accessing, iterating, and conditionally rendering this data is the key to unlocking its potential. Furthermore, advanced techniques such as namespacing with subdirectories, cross-referencing between data sources, and customizing data parsing provide the tools necessary to scale a Jekyll project without sacrificing organization or maintainability. By understanding both the powerful capabilities and the inherent limitations of Jekyll’s native data handling, developers can make informed architectural decisions, creating robust static websites that are dynamic in function and simple in form.

“`