Skip to main content

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.yaml is 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: in data/site.yaml, read as site.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 as item.
  • Each item also gets a url field. 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: title or name, description or summary, and image.
  • 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 %}
  • where matches 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.

Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.

Built in a chat

Home page of Low Tide Coffee, a coffee shop website built with SiteShip

Coffee shop

Low Tide Coffee

The prompt that built it

Build a website for Low Tide Coffee, a small coffee shop and roastery at 14 Harbor Street, Beaufort, SC. We roast our own beans in the back room. Open every day 7am to 3pm. Phone (843) 555-0114. A menu with prices (drip, cortado, cold brew, oat-milk latte, biscuits and pastries). Two house blends sold in the shop: Marsh Blend and Dock Street Dark. Catering for offices and events, with an enquiry form (name, email, date, number of people, message). Pages: Home, Menu, Our beans, Catering. Look: warm and moody. Dark roasted brown and cream with a burnt-orange accent, an elegant serif for headlines with a clean sans for text, a photo of coffee being poured in the hero, and a menu laid out like a printed cafe menu.

Swap in your own business details. Your AI will ask five quick questions if anything is missing.

Add SiteShip to your AI

SiteShip is a connector you add once. You'll create your free account when you connect. No card needed.

https://app.siteship.ai/mcp
ChatGPT
  1. Open ChatGPT on the web and go to Settings, then Apps and connectors.
  2. Choose Add custom connector (you may need to switch on Developer mode under Advanced).
  3. Name it SiteShip, paste the address above and choose OAuth.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Custom connectors need a paid ChatGPT plan.

Claude
Add to Claude

This opens Claude with SiteShip filled in. Click Add, sign in to SiteShip, then say: Get started with SiteShip.

Or add it by hand

  1. Open Claude and go to Customize, then Connectors.
  2. Click Add, then Add custom connector.
  3. Name it SiteShip and paste the address above.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.
Grok

Go to grok.com/connectors, choose New Connector, then Custom, and paste the address above.

Gemini

In the Gemini web app, open Apps/Connectors settings, add a custom connector and paste the address above. (US accounts only for now.)

Other AI apps and coding tools
  1. Open your AI app's settings and look for Connectors, Apps, Integrations or MCP servers.
  2. Add a custom (remote) connector and paste the address above.
  3. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Works with any app that accepts a remote MCP server, including coding tools such as Claude Code, Cursor, VS Code and Codex.

Coding tools

Claude Code

claude mcp add --transport http siteship https://app.siteship.ai/mcp

Codex

codex mcp add siteship --url https://app.siteship.ai/mcp

Then say: Get started with SiteShip.