Data Files
In addition to the built-in variables available from Bridgetown, you can specify your own custom data that can be accessed via Liquid.
Bridgetown supports loading data from YAML, JSON, CSV, and TSV files located in the _data
folder.
Note that CSV and TSV files must contain a header row.
This powerful feature allows you to avoid repetition in your templates and to
set site specific options without changing bridgetown.config.yml
.
Table of Contents
- The Data Folder
- The Metadata File
- Example: List of members
- Subfolders
- Example: Accessing a specific author
The Data Folder
The _data
folder is where you can store additional data for Bridgetown to use when
generating your site. These files must be YAML, JSON, or CSV files (using either
the .yml
, .yaml
, .json
or .csv
extension), and they will be
accessible via site.data
.
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 Bridgetown, etc. in your Liquid templates.
Example: 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>