Data Files

In addition to built-in variables and front matter, you can specify custom datasets which are accessible via Liquid and Ruby templates as well as plugins.

Bridgetown supports loading data from YAML, JSON, CSV, and TSV files located in the src/_data folder. Note that CSV and TSV files must contain a header row.

And starting in Bridgetown v0.21, you can save standard Ruby files (.rb) to _data which get automatically evaluated. The return value at the end of the file can either be an array or any object which responds to to_h (and thus returns a Hash). (Requires you to be using the Resource content engine.)

This powerful feature allows you to avoid repetition in your templates and set site-specific options without changing bridgetown.config.yml—and in the case of Ruby data files, perform powerful processing tasks to populate your site content.

The Data Folder
The Metadata File
Example: Define a List of members
Subfolders
Example: Accessing a specific author

The Data Folder

The _data folder is where you can save YAML, JSON, or CSV files (using either the .yml, .yaml, .json or .csv extension), and they will be accessible via site.data. In Bridgetown 0.21 and later, any files ending in .rb within the data folder will be evaluated as Ruby code when using the Resource content engine.

The Metadata File

You can store site-wide metadata variables in _data/site_metadata.yml so they’ll be easy to access and will regenerate pages when changed. This is a good place to put <head> content like your website title, description, favicon, social media handles, etc. Then you can reference site.metadata.title, etc. in your Liquid and Ruby templates.

Want to switch to using a site_metadata.rb file where you have more programmatic control over the data values, can easily load in ENV variable, etc.? Now you can! For example:

# src/_data/site_metadata.rb
{
  title: "Your Ruby Website",
  lang: ENV["LANG"],
  tagline: "All we need is Ruby"
}

Example: Define a List of members

Here is a basic example of using Data Files to avoid copy-pasting large chunks of code in your Bridgetown templates:

In _data/members.yml:

- name: Eric Mill
  github: konklone

- name: Parker Moore
  github: parkr

- name: Liu Fengyun
  github: liufengyun

Or _data/members.csv:

name,github
Eric Mill,konklone
Parker Moore,parkr
Liu Fengyun,liufengyun

This data can be accessed via site.data.members (notice that the filename determines the variable name).

You can now render the list of members in a template:

<ul>
{% for member in site.data.members %}
  <li>
    <a href="https://github.com/{{ member.github }}" rel="noopener">
      {{ member.name }}
    </a>
  </li>
{% endfor %}
</ul>

Subfolders

Data files can also be placed in subfolders of the _data folder. Each folder level will be added to a variable’s namespace. The example below shows how GitHub organizations could be defined separately in a file under the orgs folder:

In _data/orgs/bridgetownrb.yml:

username: bridgetownrb
name: Bridgetown
members:
  - name: Jared White
    github: jaredcwhite

  - name: Gilbert the Cat
    github: gilbertkitty

In _data/orgs/doeorg.yml:

username: doeorg
name: Doe Org
members:
  - name: John Doe
    github: jdoe

The organizations can then be accessed via site.data.orgs, followed by the file name:

<ul>
{% for org_hash in site.data.orgs %}
{% assign org = org_hash[1] %}
  <li>
    <a href="https://github.com/{{ org.username }}" rel="noopener">
      {{ org.name }}
    </a>
    ({{ org.members | size }} members)
  </li>
{% endfor %}
</ul>

Example: Accessing a specific author

Pages and posts can also access a specific data item. The example below shows how to access a specific item:

_data/people.yml:

dave:
  name: David Smith
  twitter: DavidSilvaSmith

The author can then be specified as a page variable in a post’s front matter:

---
title: sample post
author: dave
---

{% assign author = site.data.people[page.author] %}
<a rel="author noopener"
  href="https://twitter.com/{{ author.twitter }}"
  title="{{ author.name }}">
    {{ author.name }}
</a>

Next: Prototype Pages