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
- 01Read a site’s source tree and say what each folder is for.
- 02Write a record, and say which formats a record can take.
- 03Generate one page per record with for_each, and paged lists with per_page.
- 04Group pages by tag or category and generate an index page for each.
- 05Explain why a render reads only the source tree, and what that guarantees.
- 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
- 1001Your first siteWhat a site is, the working copy called dev, the first release, the address it answers at, and who may create one.
- 1002Dev, promote, roll backEnvironments people use, promotion of the exact release that was reviewed, approval, rollback, and the history of every move.
- 1003Private environments, public domainsAccess per environment: people, personas, everyone internal, the sign-in every pages address asks for, and the rules for making a domain public.
- 1004Your own domainThe main address, an address for every environment, adding a domain in the portal, making it public, and the names a site cannot take.
- 1005Layouts and recordsLayouts, includes and records: the agent maintains data and the platform generates pages, paged lists and category indexes.
- 1006Editing a live siteReading and patching site files in place, dry runs and diffs, overlays for new files, and one promotion for several edits.
- 1007Capstone: moving an existing site onto PlexaraA crawl that keeps every address, redirects as rules, forms replaced by Plexara forms, and the whole series end to end.
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
- 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.
- 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.
- 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.
- 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.
