Documentation Writing Content

Data Files

In addition to standard resources, 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.

You can also 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).

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.

Table of Contents #

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 Also, any files ending in .rb within the data folder will be evaluated as Ruby code with a Hash formatted output.

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:

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

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

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

{% for member in %}
    <a href="{{ member.github }}" rel="noopener">
      {{ }}
{% endfor %}

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
  - name: Jared White
    github: jaredcwhite

  - name: Gilbert the Cat
    github: gilbertkitty

In _data/orgs/doeorg.yml:

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

The organizations can then be accessed via, followed by the file name:

{% for org_hash in %}
{% assign org = org_hash[1] %}
    <a href="{{ org.username }}" rel="noopener">
      {{ }}
    ({{ org.members | size }} members)
{% endfor %}

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:


  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 =[] %}
<a rel="author noopener"
  href="{{ author.twitter }}"
  title="{{ }}">
    {{ }}

Static Files