Skip to main content
Architecture12 min read

1005 - Layouts and records

A site with a layouts folder is rendered when it is published. The agent keeps content as records, one file per store, product or post, and the platform generates the pages, the paged lists and the category indexes from them. Layouts, includes, front matter, for_each and per_page, and why a render is a function of the source and nothing else.

What you will take away from this lesson

The store finder from lesson 1001 is one long page the agent wrote by hand from a query. ACME has 303 stores, each deserves a page of its own, and a store that opens next month should not mean rewriting a website.

This lesson turns the site into records and layouts. The agent keeps one small file per store. The platform turns those files into every page, every list and every index when the site is published. Nobody runs a build, because there is no build tool: rendering is part of publishing.

Learning Objectives

  1. 01Read a site’s source tree and say what each folder is for.
  2. 02Write a record, and say which formats a record can take.
  3. 03Generate one page per record with for_each, and paged lists with per_page.
  4. 04Group pages by tag or category and generate an index page for each.
  5. 05Explain why a render reads only the source tree, and what that guarantees.
  6. 06Say what happens when a template is wrong.

Where this lesson sits

After lesson 1004, acme-stores is public on stores.example.com and serves release 2: five files, one of them a single long page listing every store. dev serves release 3.

1000 Series: Sites

Open index

The 1000 series builds on the forms and endpoints of the 700 series and the sharing model of the 800 series: a site is where the pages people open live, with the same people, personas and approvals deciding who reaches them.

The request

Grace asked for the site to be rebuilt around its data. She did not ask for a content management system, a static site generator, or a build pipeline, because none of those is needed.

What you type

Rebuild acme-stores so every store has its own page. Keep each store as a record with its name, address, city, state, phone, opening hours and coordinates, taken from the warehouse. Generate a page per store, a store list 25 to a page, and a news section where each post is a Markdown file with tags. Share one layout and one navigation across every page.

The source tree

The agent replaced five hand-written files with a source tree. Folders whose names begin with an underscore are instructions to the platform; everything else is a page or a file to copy.

The source of a rendered site

acme-stores (source)
├── _layouts/
│   ├── base.html            the page shell: head, navigation, footer
│   └── store.html           one store, wrapped by base
├── _includes/
│   ├── nav.html
│   └── hours.html           the opening-hours table
├── _data/
│   └── stores/
│       ├── 0001-chicago-loop.json
│       ├── 0002-evanston.json
│       └── ... 303 records, one per store
├── index.html               a page: it has front matter
├── stores/
│   ├── index.html           the paged store list
│   └── store.html           the template for_each turns into 303 pages
├── news/
│   ├── holiday-hours.md     a post, written in Markdown
│   └── tags.html            one index page per tag
├── sitemap.xml              a page that loops over every other page
├── assets/site.css          no front matter: copied as it is
└── 404.html

A site with a _layouts folder is rendered when it is published. A site without one is served exactly as published, which is the site lesson 1001 built. The folder is the whole switch.

What each part is

There are five kinds of thing in a source tree, and each has one job.

What each part of the source is

Layouts

_layouts/<name>.html

A Liquid template that wraps a page’s content. A layout can name a parent layout, so store.html adds a map and an hours table inside the shell base.html provides.

Includes

_includes/<file>

A fragment shared between layouts and pages: the navigation, a footer, an opening-hours table. An include can see the page’s variables or be handed exactly the values it needs.

Records

_data/<collection>/<file>

One record per file, as JSON, YAML, or Markdown with front matter. A folder of records is a collection, and templates read it as site.data.<collection>. A record’s slug is its file name unless it says otherwise.

Pages

any .html, .md, .xml, .json or .txt with front matter

A file that begins with front matter is a page: its body is rendered and wrapped in its layout. A Markdown page is turned into HTML.

Everything else

no front matter

Copied to the release as it is: stylesheets, scripts, images, fonts, a page that needs no layout.

A record

A record is one file describing one thing. ACME’s stores collection has one record per store, written from the same warehouse table the store operations team reports from.

One record

_data/stores/0001-chicago-loop.json

{
  "name": "ACME Chicago Loop",
  "store_id": 1,
  "address": "200 N. Example Street",
  "city": "Chicago",
  "state": "IL",
  "region": "Midwest",
  "phone": "555-0100",
  "latitude": 41.8837,
  "longitude": -87.6325,
  "hours": [
    { "days": "Monday to Saturday", "open": "9:00 AM", "close": "9:00 PM" },
    { "days": "Sunday",             "open": "10:00 AM", "close": "6:00 PM" }
  ]
}

The agent wrote 303 of these from one warehouse query. A record is plain data with no markup in it, which is why it is safe to regenerate: an automation that refreshes store records from the warehouse changes facts and cannot break a layout. A record written in Markdown carries its fields in front matter and its body as content.

One page per record

A page template with for_each is rendered once for every record in a collection. The template is written once, reviewed once, and applied 303 times.

One template, 303 pages

stores/store.html

---
layout: store
for_each: stores
permalink: /stores/{{ item.slug }}/
---
<h1>{{ item.name }}</h1>
<p>{{ item.address }}, {{ item.city }}, {{ item.state }}</p>
<p><a href="tel:{{ item.phone }}">{{ item.phone }}</a></p>
{% include "hours.html", hours: item.hours %}


_layouts/store.html

---
layout: base
---
<article class="store">
  {{ content }}
  <div id="map" data-lat="{{ item.latitude }}" data-lng="{{ item.longitude }}"></div>
</article>

for_each: stores renders this page once per record in the collection, with the record as item. The permalink decides each page’s address, so the Chicago Loop store answers at /stores/0001-chicago-loop/. Add a record and the next publish has one more page. Remove one and its page is gone.

Paged lists and index pages

Two more templates finish the site: a store list that pages itself, and a news index that makes a page for every tag a post carries.

Paged lists and one index page per tag

stores/index.html

---
layout: base
title: Store finder
for_each: stores
per_page: 25
permalink: /stores/page/{{ paginator.page }}/
---
<h1>Stores, page {{ paginator.page }} of {{ paginator.total_pages }}</h1>
<ul>
{% for store in paginator.items %}
  <li><a href="/stores/{{ store.slug }}/">{{ store.name }}</a>, {{ store.city }}, {{ store.state }}</li>
{% endfor %}
</ul>
{% if paginator.next_page %}<a href="/stores/page/{{ paginator.next_page }}/">Next</a>{% endif %}


news/tags.html

---
layout: base
for_each: tags
permalink: /news/tags/{{ item.slug }}/
---
<h1>News tagged {{ item.name }}</h1>
{% for post in item.pages %}<a href="{{ post.url }}">{{ post.title }}</a>{% endfor %}

With per_page, the page is rendered once per group of records and paginator carries the group, the page number, the totals and the neighbours. With for_each: tags or categories, it is rendered once per value used anywhere on the site, and item carries the value’s name and the pages that have it. A sitemap or a feed is an ordinary page that loops over site.pages.

Front matter

Front matter is the short block of fields at the top of a file, between two lines of three dashes. It is what makes a file a page and tells the platform how to render it.

Front matter keys

layout

The layout that wraps this page. A layout’s own front matter can name its parent.

title, date

The page’s own fields, read by layouts and by lists of pages.

permalink

The address the page is served at. It can use the record or the page number, as the store and list pages do.

tags, categories

Values the page is grouped under, for index pages.

for_each

A collection, tags or categories: render this page once per record or value.

per_page

With for_each: render once per group of this many, for paged lists.

draft

True keeps the page in the source and out of what is published.

liquid: false

Leaves the body alone, for a page whose own script uses double braces.

Publishing renders the site

There is no separate step called build. The agent saved the source to a folder in the library and published that folder.

Publishing the source renders the site

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "publish", "site": "acme-stores",
    "folder": "sites/acme-stores/source",
    "note": "Rendered site: a page per store, paged list, news with tags" }

← { "release": { "number": 4, "source": "sites/acme-stores/source",
                 "note": "Rendered site: a page per store, paged list, news with tags" },
    "environment": "dev",
    "address": "https://acme-stores--dev.pages.example.com/" }

The publish call is the one from lesson 1001. The platform saw the layouts folder, rendered every page, and wrote release 4 with two trees in it: the source the agent published, and the output a browser is served. The source came from a folder in the library because 303 records are more than one call should carry inline.

What release 4 holds

What release 4 holds

store records in _data/stores
303
store pages, from one template
303
list pages, 25 stores to a page
13
build tools installed or run
0

The site grew from five files to several hundred pages and the amount the agent has to get right shrank: two layouts, two includes, three page templates, and data.

Source and output

A rendered release keeps what was written and what was produced, separately, and knows how one led to the other.

A rendered release holds two trees

The source

what you edit

Layouts, includes, records and page templates. The people who manage the site and their agents read and change it. It is never served, because it is not in the tree a browser is served from.

The output

what is served

The rendered pages and the copied files. Someone the site is shared with, and every visitor, reads only this.

What ties them together

recorded with the release

The platform records which source files each output read. Change one store record and only that store’s page and the lists it appears in are rendered again. Change a layout and every page that uses it is rendered again, in the same release.

What a render guarantees

Templates are written by people and agents and run inside the platform, so the platform puts four guarantees around every render.

What a render guarantees

  1. 01

    A render reads the source tree and nothing else

    A template reaches no network, no clock and no file outside the tree. Asking for the current date is refused: a date comes from a page or a record. The same source always renders to the same site.

  2. 02

    A wrong template refuses the release

    A template error stops the publish, names every file and line that failed, and leaves dev serving the release it served before. A half-rendered site is never published.

  3. 03

    Every render is bounded

    Rendering runs inside the platform, so each render has a five-minute deadline and limits on loop iterations, on how deeply includes and blocks nest, and on the size of a page and of the whole output. A runaway loop fails its page; it does not slow anything else.

  4. 04

    A dry run renders without publishing

    An edit can be tried first: the dry run reports how many served files would change and any template error, and writes nothing. Lesson 1006 uses it.

Data in, pages out

What comes next

Release 4 is in dev, waiting for review and promotion as in lesson 1002. Lesson 1006 changes one store’s hours and adds a store, without resending the site.

Key terms

Five terms cover how a site is generated from records.

Key Terms

Layout
A Liquid template in _layouts that wraps a page’s content. Its presence is what makes a site rendered at publish.
Record
One file in _data/<collection>: JSON, YAML, or Markdown with front matter. Templates read a collection as site.data.<collection>.
Front matter
The fields at the top of a file, between two lines of three dashes. A file that has it is a page.
for_each
Front matter that renders a page once per record of a collection, or once per tag or category.
Source and output
The two trees of a rendered release: what the people who manage the site edit, and what a browser is served.