For your AI and the curious
Data files and generated pages
Lists live in data/ as JSON. A list can have a page for each item, lists can point at each other, and group_by sorts items into groups.
On this page
Anything a site has more than one of is a list: a JSON file in data/. Every template reads it as data.<name>. A list can have a page for each item, and lists can point at each other.
This page is the data-pages topic of the connector's guide tool.
Lists in data/
data/services.json → data.services
data/team.json → data.team
data/faq.json → data.faq
data/practice-areas.json → data.practice-areas
A list is a plain array of objects:
[
{ "slug": "whitening", "name": "Teeth Whitening", "summary": "Whiter teeth in one visit.", "price": "$299" },
{ "slug": "implants", "name": "Dental Implants", "summary": "A permanent fix for a missing tooth.", "price": "From $1,900" }
]
Loop over it in any page or partial. There is nothing to import or configure:
{% for s in data.services %}
<a href="{{ s.url }}">{{ s.name }}</a>
{% endfor %}
Rules:
- Lists are JSON.
data/site.yamlis the only YAML file. - Keep a list a flat array of objects.
- A hyphen in the file name works:
data.practice-areas. - The site menu is not a data file. It is
menu:indata/site.yaml, read assite.menu. - Guard optional fields:
{% if item.price %}…{% endif %}. - A file that does not parse is refused (
author.data_file_invalid). - Real content only. A list of team members, reviews or testimonials holds what the owner gave, never invented entries.
The FAQ list
data/faq.json is the one list with fixed keys, question and answer:
[{ "question": "Do you take walk-ins?", "answer": "Yes, until 4pm on weekdays." }]
Add type: faq to the frontmatter of the page that shows it, and SiteShip writes FAQPage schema on that page. Without type: faq there is no FAQ schema.
A page per item
Give each item a slug: lowercase words joined by hyphens. Then write pages/services/[slug].html. The folder name ties the page to data/services.json, and the file needs no frontmatter:
<section class="max-w-3xl mx-auto px-6 py-16">
<h1 class="text-4xl font-bold">{{ item.name }}</h1>
<p class="mt-4">{{ item.summary }}</p>
<p class="mt-4 font-semibold">{{ item.price }}</p>
</section>
- Each item gets a page at
/services/<slug>, with the entry asitem. - Each item also gets a
urlfield. Link with{{ s.url }}; don't build the address by hand. - A slug that is not in the data is a 404.
- The page's title, description and share image come from the item:
titleorname,descriptionorsummary, andimage. - To override one, set it in the frontmatter. Liquid works there:
title: "{{ item.name }} in {{ site.address.city }}"
If data/services.json does not exist yet, the page is written, but publish is blocked until it does (author.generate_from_not_list). That lets a page land before its data.
Generated pages are in the sitemap. In site search they are found by title and description, plus any item fields the template opts in with search: { fields: [category] } in its frontmatter.
route.generate
A [param] page that is not a plain pages/<list>/[slug].html names its list in the frontmatter. Without it the write is refused (author.dynamic_route_missing_generate).
This file is pages/[category]/[slug].html:
---
route:
generate:
from: rooms # data/rooms.json
params:
category: category # [category] = each item's category field
slug: slug
where:
status: published # optional: only these items
---
<h1>{{ item.name }}</h1>
Use route.generate only for these cases:
- the list has another name than the folder;
- the address uses another field than the param's name;
- only some items get a page (
where); - the page is in a nested folder;
- the address has two params.
from: rooms.items reads a list held inside an object.
Related diagnostics:
| Code | Meaning |
|---|---|
author.dynamic_route_param_missing |
A [param] in the path has no mapping |
author.dynamic_route_param_unused |
A mapping names a param the path does not have |
author.generate_no_pages |
The list makes no pages |
author.generate_items_skipped |
Some items lack the field the address needs |
author.slug_not_url_safe |
A slug is not safe to use in an address |
Lists that point at each other
A relationship is a slug in a field, looked up with where. Name the field after the list it points at (location or locations for data/locations.json), so SiteShip can check it.
// data/locations.json
[{ "slug": "uluwatu", "name": "Uluwatu" }, { "slug": "canggu", "name": "Canggu" }]
// data/agents.json: an agent covers several locations
[{ "slug": "made", "name": "Made Wijaya", "locations": ["uluwatu", "canggu"] }]
// data/villas.json: a villa has one location and one agent
[{ "slug": "ocean-view", "name": "Ocean View Villa", "location": "uluwatu", "agent": "made" }]
From a villa to its location and agent, in pages/villas/[slug].html:
{% assign loc = data.locations | where: "slug", item.location | first %}
{% assign agent = data.agents | where: "slug", item.agent | first %}
<h1>{{ item.name }}</h1>
<p><a href="{{ loc.url }}">{{ loc.name }}</a>, with {{ agent.name }}</p>
From a location to its villas and agents, in pages/locations/[slug].html:
{% assign villas = data.villas | where: "location", item.slug %}
{% assign agents = data.agents | where: "locations", item.slug %}
<p>{{ villas | size }} villas, {{ agents | size }} agents</p>
{% for v in villas %}<a href="{{ v.url }}">{{ v.name }}</a>{% endfor %}
wherematches a plain field by its value. When the field holds a list, it matches if the list contains the value.- Count with
size. A count typed into the data, such as"villas": 12, goes stale and is reported (author.hand_typed_count). - A slug that matches no item, such as
"location": "ubudd", is reported with the closest real slug (author.broken_reference). It does not stop the write. It blocks publish.
group_by
group_by returns a list of groups. Each group has name, the field's value, and items:
{% assign groups = data.menu | group_by: "category" %}
{% for g in groups %}
<h2>{{ g.name }}</h2>
{% for dish in g.items %}
<p>{{ dish.name }} <span>{{ dish.price }}</span></p>
{% endfor %}
{% endfor %}
Groups keep the order in which each value first appears in the list.
Related pages
Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.