Data files

A data/ directory beside content/ holds structured values that layouts read directly, so a list of authors, a set of social links, or a navigation table lives in one place rather than being repeated across templates.

The data tree#

Every .json, .yaml, and .yml file under data/ loads into a data structure keyed by filename without the extension. Subdirectories nest. When two files share a name, such as authors.json and authors.yaml, the last in sort order wins, so .yml beats .yaml beats .json.

data/
  authors.json      -> data<authors>
  site/
    links.yaml      -> data<site><links>

data/authors.json:

{ "name": "Greg Donald", "url": "https://blogin.dev" }

A layout reaches it with a hash subscript:

%p.byline
  %a{href: "#{data<authors><url>}"}= data<authors><name>

JSON and YAML read into the same structure. YAML is read as a subset: block mappings and sequences, scalars, inline [a, b] lists, and comments. See Data File YAML for what it refuses.

links:
  - title: Feed
    href: /feed.xml

Directory-scoped data#

A _data.json, _data.yaml, or _data.yml file inside a content directory applies to the pages in and beneath that directory, overriding a matching key from the site-wide data/ tree. Deeper directories override shallower ones, and content/_data.json applies to every page. A _data file must be a mapping, and one whose top level is a list is ignored. A directory holding more than one merges them in the order .json, .yaml, .yml.

content/
  posts/
    _data.json      -> merges for every page under posts/

Given data/banner.json set to "Site banner" and content/posts/_data.json of { "banner": "Posts banner" }, a post under posts/ reads data<banner> as Posts banner, while a page elsewhere reads Site banner. Nested hashes merge key by key, so a scoped file overrides only the keys it names and leaves the rest of the tree in place.

Section listings resolve data the same way, so index.haml for a section sees that section's scoped values.