| `title` |
string |
yes |
The `
`. Also the visible `h1` when no block supplies one and no `heading` is set
</td>
</tr>
<tr>
<th scope="row">`heading`</th>
<td>string</td>
<td>no</td>
<td>The visible `h1`, when it should differ from the tab title. A tab title often carries the site name; a heading never should</td>
</tr>
<tr>
<th scope="row">`description`</th>
<td>string</td>
<td>yes</td>
<td>Meta description and Open Graph description. 50 to 160 characters</td>
</tr>
<tr>
<th scope="row">`layout`</th>
<td>enum</td>
<td>yes</td>
<td>A file in `layouts/`. Defaults to `page`</td>
</tr>
<tr>
<th scope="row">`nav`</th>
<td>string</td>
<td>no</td>
<td>Which nav item gets `aria-current="page"`</td>
</tr>
<tr>
<th scope="row">`updated`</th>
<td>date</td>
<td>no</td>
<td>Rendered where the layout calls for it</td>
</tr>
<tr>
<th scope="row">`noindex`</th>
<td>boolean</td>
<td>no</td>
<td>Adds the robots directive and drops the page from the sitemap</td>
</tr>
<tr>
<th scope="row">`og`</th>
<td>map</td>
<td>no</td>
<td>Per-page Open Graph overrides</td>
</tr>
<tr>
<th scope="row">`redirects`</th>
<td>list</td>
<td>no</td>
<td>Old paths that should land here. Written into `_redirects`</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
<section class="section">
<div class="wrap">
<p>Anything not in the layout's declared frontmatter schema is an error, so a typo in a key surfaces at check time instead of silently doing nothing.</p>
<p>Locale is carried by the file's path rather than by a frontmatter field: <code>src/content/es/displays/index.md</code> serves <code>/es/displays/</code>. See <a href="/translation/">TRANSLATION.md</a>.</p>
<h2>Blocks</h2>
<p>A block opens with <code>:::type</code> on its own line and closes with <code>:::</code> on its own line. Everything between is YAML. Nothing nests.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<pre class="code" tabindex="0">:::cards
heading: One platform, three layers
items:
- title: Data platform
href: /developers/
:::</pre>
</div>
</section>
<section class="section">
<div class="wrap">
<p>The splitter takes those regions as raw text before any markdown parsing happens, so YAML is never reinterpreted by the markdown parser. Text outside any block is collected into <code>prose</code> blocks.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="section-head">
<h2>How much of this is invented</h2>
</div>
<p>Two conventions, and neither is new.</p>
<p><strong><code>:::type</code> containers</strong> are the CommonMark generic directives proposal, the syntax <code>remark-directive</code> implements and the one Docusaurus, Astro, and most MDX-adjacent tooling already use for admonitions and custom blocks. An author who has written documentation in the last few years has seen it.</p>
<p><strong>YAML</strong> is already in the frontmatter of every markdown file everywhere.</p>
<p>What the engine adds on top is one rule: a container's body is YAML rather than markdown. That rule exists so there is never a question about how a block's contents are read, and it is the only thing here a person has to be told.</p>
<p>Everything else is the component vocabulary, which is a vocabulary rather than a syntax. <code>:::hero</code> has to be documented the same way a function has to be documented, and it is, from the schema that defines it.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="section-head">
<h2>Documentation, generated from the schemas</h2>
</div>
<p>One source, three renderings.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="scroller" tabindex="0" aria-label="Documentation, generated from the schemas">
<table>
<caption>Documentation, generated from the schemas</caption>
<thead>
<tr>
<th scope="col">Rendering</th>
<th scope="col">Command</th>
<th scope="col">For</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">`docs/components/*.md`, committed</th>
<td>`cms docs`</td>
<td>A person reading the repo</td>
</tr>
<tr>
<th scope="row">The `components` prompt slot</th>
<td>`cms sync`</td>
<td>The editing agent</td>
</tr>
<tr>
<th scope="row">The validator</th>
<td>every `cms check`</td>
<td>The build</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
<section class="section">
<div class="wrap">
<p><code>cms docs</code> writes a page per component: what the block is for, when to reach for it and when not to, every field with its type and its help text, the accessibility rules attached to it, a worked example, and the HTML it produces. <code>cms explain hero</code> prints the same thing in the terminal.</p>
<p>Because all three come from <code>schema.yml</code>, a field added without help text shows up as a gap in the human documentation on the next build, which is the pressure that keeps the reference worth reading. A component whose documentation drifts from its validator is not a state the system can reach.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="section-head">
<h2>Fields every block has</h2>
</div>
<p>Two fields exist on every block without appearing in any component's schema.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="scroller" tabindex="0" aria-label="Fields every block has">
<table>
<caption>Fields every block has</caption>
<thead>
<tr>
<th scope="col">Field</th>
<th scope="col">Type</th>
<th scope="col">For</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">`id`</th>
<td>text, max 64</td>
<td>A stable anchor, rendered as the section id. Lowercase, hyphenated. Uniqueness is checked across the page</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<p>They live on the block rather than in each schema because every block can take them and repeating them eighteen times would guarantee they drift.</p>
<p><strong>A block with no content at all is an error.</strong> With optional fields that is reachable by accident, and a block that renders as nothing still occupies a position in the page and a line in <code>cms outline</code>.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="section-head">
<h2>Headings inside a block</h2>
</div>
<p>A block's markdown body can use any heading level, and the renderer normalises them: whatever the author used as their top level becomes the floor, and everything below keeps its relative depth.</p>
<p>The floor is <code>h2</code> for a plain block, or <code>h3</code> for a block that emits its own heading. So <code>##</code> and <code>###</code> as a top level both work, and neither produces a skipped level or a second <code>h1</code>.</p>
<p>This exists because the page owns its <code>h1</code>. A legal page written as plain markdown starting with <code>#</code> would otherwise produce two, and the heading tree would be unnavigable.</p>
<p>Relatedly, a layout supplies the page heading <strong>only when no block already did</strong>. A <code>legal</code> layout renders <code>title</code> as an <code>h1</code>, unless the page has a hero, which carries its own.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="section-head">
<h2>Field types</h2>
</div>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="scroller" tabindex="0" aria-label="Field types">
<table>
<caption>Field types</caption>
<thead>
<tr>
<th scope="col">Type</th>
<th scope="col">Accepts</th>
<th scope="col">Rendered as</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">`text`</th>
<td>plain string</td>
<td>escaped text, no markup</td>
</tr>
<tr>
<th scope="row">`inline`</th>
<td>string with inline markdown</td>
<td>links, `strong`, `em`, `code`, entities</td>
</tr>
<tr>
<th scope="row">`markdown`</th>
<td>block markdown</td>
<td>paragraphs, lists, headings within the block's level</td>
</tr>
<tr>
<th scope="row">`href`</th>
<td>internal path or absolute URL</td>
<td>resolved and link-checked; external links get `target` plus the visually-hidden new-tab note</td>
</tr>
<tr>
<th scope="row">`media`</th>
<td>a name in `src/media/`</td>
<td>a full `
<picture>
` with generated `srcset` and computed `sizes`
</td>
</tr>
<tr>
<th scope="row">`icon`</th>
<td>a name in the icon set</td>
<td>inline SVG with `aria-hidden="true"`</td>
</tr>
<tr>
<th scope="row">`enum`</th>
<td>one of a listed set</td>
<td>whatever the template does with it</td>
</tr>
<tr>
<th scope="row">`list<T>`</th>
<td>a YAML sequence</td>
<td>repeated, with `min` and `max` enforced. Nests, so `list<list<inline>>` is a table's rows</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<p>A <code>media</code> field takes a bare name, with no path and no extension. Passing <code>img/photo.jpg</code> is an error rather than a guess, because the build decides the format and the widths.</p>
<p><code>text</code> versus <code>inline</code> is the lever that keeps markup out of places it does not belong. A card title is <code>text</code>, so no one can put a link inside a heading that is already inside a link. A card body is <code>inline</code>, so a term can carry a reference.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="section-head">
<h2>Block schemas</h2>
</div>
<p>Every component ships a schema. The validator reads it, and so does the generator that writes the component reference into the agent's prompt.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<pre class="code" tabindex="0"># components/cards/schema.yml
name: cards
summary: A grid of linked cards. The standard way to route from an overview
page to its sections.
band: auto # auto | light | alt | dark
fields:
heading: { type: inline, required: false }
lead: { type: inline, required: false, max_chars: 220 }
tag: { type: text, required: false, max_chars: 24 }
columns: { type: enum, values: [2, 3, 4], default: 3 }
items:
type: list<card>
min: 2
max: 8
types:
card:
title: { type: text, required: true, max_chars: 48 }
body: { type: inline, required: true, max_chars: 240 }
href: { type: href, required: false }
icon: { type: icon, required: false }
more: { type: text, required: false, help: "The affordance text. Must
name the destination, because WCAG 2.4.9 asks that a link make
sense read on its own." }
accessibility:
- Each card is a single link, so the title must not repeat the more text.
- Two cards on a page may not share more text unless they share a target.</pre>
</div>
</section>
<section class="section">
<div class="wrap">
<p><code>classes_max</code> caps how many CSS classes the component's template may emit, which is how "minimal classes" becomes a number rather than a preference. <code>owns_layout: true</code> means the component wraps its own content and the renderer must not add the standard <code>.wrap</code>; only <code>shots</code> needs it, to escape the content column. <code>sizes_by</code> points a media slot at a sibling field so one slot can declare a different <code>sizes</code> expression per value of that field.</p>
<p><code>band</code> lets a block declare where it sits in the light and dark alternation, or leave it to the renderer. <code>summary</code> and <code>help</code> are what the agent reads, so they are written for that audience. <code>accessibility</code> entries become check rules and also appear in the prompt, so the reason a constraint exists travels with the constraint.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="section-head">
<h2>Component catalogue</h2>
</div>
<p>Every component maps to markup already in <code>base.css</code> v2. Nothing here invents a class. The engine's class allowlist is built by parsing the stylesheet, so a component that reached for a class the CSS does not define would fail the build.</p>
<h3>Structure</h3>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="scroller" tabindex="0" aria-label="Component catalogue">
<table>
<caption>Component catalogue</caption>
<thead>
<tr>
<th scope="col">Block</th>
<th scope="col">Renders</th>
<th scope="col">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">`prose`</th>
<td>`.section > .wrap` with running text</td>
<td>The implicit type for bare markdown</td>
</tr>
<tr>
<th scope="row">`hero`</th>
<td>`.hero > .wrap.hero-grid`</td>
<td>First block on a landing page. Always a dark band. Carries the `h1`</td>
</tr>
<tr>
<th scope="row">`split`</th>
<td>`.split > .split-panel`</td>
<td>Two panels, each with a heading, body, and one button</td>
</tr>
<tr>
<th scope="row">`features`</th>
<td>`.feature-row > .copy + .media`</td>
<td>Copy beside media. `flip` and `uneven` are fields</td>
</tr>
<tr>
<th scope="row">`cards`</th>
<td>`.card-grid > a.card.card-link`</td>
<td>2 to 8 items, 2 to 4 columns</td>
</tr>
<tr>
<th scope="row">`steps`</th>
<td>`.steps > .step`</td>
<td>Numbered sequence. Numerals are drawn by the CSS</td>
</tr>
<tr>
<th scope="row">`ticks`</th>
<td>`ul.ticks`</td>
<td>Marked list. `style: check` swaps in `.checks`</td>
</tr>
<tr>
<th scope="row">`shots`</th>
<td>`figure.shot` with `figcaption`</td>
<td>Screenshots. Uses the media pipeline</td>
</tr>
<tr>
<th scope="row">`code`</th>
<td>`.code` with `pre > code`</td>
<td>Language field drives the token classes</td>
</tr>
<tr>
<th scope="row">`table`</th>
<td>`table` in a scrolling wrapper</td>
<td>Header row required, caption required</td>
</tr>
<tr>
<th scope="row">`faq`</th>
<td>`details` group</td>
<td>Each item is a `summary` plus body</td>
</tr>
<tr>
<th scope="row">`plain`</th>
<td>`details.plain-summary`</td>
<td>The plain-language summary. See below</td>
</tr>
<tr>
<th scope="row">`proof`</th>
<td>`.proof`</td>
<td>Dark strip for logos and a claim. The one place amber is text</td>
</tr>
<tr>
<th scope="row">`cta`</th>
<td>`.cta-band`</td>
<td>Closing ask. Dark band</td>
</tr>
<tr>
<th scope="row">`embed`</th>
<td>`iframe` in a framed figure</td>
<td>Requires a title, a fallback link, and a declared aspect ratio</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<h2>Chrome</h2>
<p>Header, nav, and footer are partials driven by <code>src/data/site.yml</code> and <code>nav.yml</code>, not blocks. A page cannot change them, which is the point: they are identical on every page, defined once.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<pre class="code" tabindex="0"># src/data/nav.yml
main:
- { id: agencies, label: Agencies, href: /agencies/ }
- { id: developers, label: Developers, href: /developers/ }
- { id: contact, label: Get in touch, href: "mailto:hello@gtfs.media", style: cta }
footer:
- heading: Product
links: [...]
legal:
- { label: Privacy policy, href: /privacy/ }
- { label: Terms of use, href: /terms/ }</pre>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<p><code>cms nav add</code> edits this file, and every page picks the change up on the next build. That replaces the current pattern of thirteen copies of the same header.</p>
<h2>The plain-language block</h2>
<p><code>plain</code> deserves its own note because it is doing accessibility work, not decoration. WCAG 3.1.5 (AAA) asks for a supplementary version of content that requires more than lower secondary reading ability. gtfs.media already ships one on its home page, as an "In plain language" disclosure.</p>
<p>The engine makes that a first-class component and the conformance ledger tracks it: a page whose prose reads above the threshold, and which has no <code>plain</code> block, is flagged. The reading-level estimate is advisory and a person attests the result, for the reasons set out in <a href="/accessibility/">ACCESSIBILITY.md</a>.</p>
</div>
</section>
<section class="section">
<div class="wrap">
<div class="section-head">
<h2>Addressing blocks</h2>
</div>
<p>Blocks carry no synthetic ids in the source. <code>cms outline</code> numbers them, and tools and conversation use those numbers.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<pre class="code" tabindex="0">$ cms outline /displays/
1 hero "Departure boards riders can actually read."
2 prose h2 "What a display shows"
3 cards 3 items, h2 "Three ways to run a screen"
4 shots 2 items
5 cta "Put your feed to work."</pre>
</div>
</section>
<section class="section">
<div class="wrap">
<p>A block that needs a stable anchor sets <code>id:</code> explicitly, and the renderer emits it on the section. Everything else gets heading-derived anchors.</p>
</div>
</section>
<section class="section section-alt">
<div class="wrap">
<div class="section-head">
<h2>Escape hatches, and where they stop</h2>
</div>
<p>The model will not cover everything. Three ways out, in order of preference.</p>
<p><strong>Generate the page.</strong> A page whose content comes from a data file rather than from an author is a generator: a site-local module that reads the data and returns blocks. gtfs.media's API reference, built from <code>openapi.yaml</code>, is the example. The blocks it returns go through schema validation, rendering, the normalizer, and every check exactly as a hand-written page's do, so a generated page carries the same guarantees as any other. This is the right answer for most things that feel like they need raw HTML.</p>
<p><strong>Add a component.</strong> If a site needs something the catalogue lacks, it lands in <code>src/components/</code> with a schema, a template, and, if it is genuinely shared, a move into the engine and into <code>base.css</code>. The rule already governing <code>site.css</code> applies unchanged: a component appearing on a second site belongs in the shared layer.</p>
<p><strong>A raw block, gated.</strong> For the genuine one-off that is neither generated nor repeated. <code>:::raw</code> takes an HTML body. It is off by default, and turning it on for a site is a line in <code>site.yml</code> that names the pages allowed to use it. Raw content still passes through the normalizer, the class allowlist, and every accessibility check, so it can bend the model without escaping the guarantees. Its presence on a page is reported by <code>cms check</code>, so raw blocks stay visible rather than becoming a quiet habit.</p>
<p>There is no fourth way out, and none of the three lets markup reach a page without passing the gate.</p>
</div>
</section>
<section class="cta-band">
<div class="wrap">
<div class="inner">
<h2>Next</h2>
<p>Continue with components.</p>
<div class="hero-ctas">
<a class="btn" href="/components/">COMPONENTS</a>
</div>
</div>
</div>
</section>
</main>
<footer class="site-footer footer-slim">
<div class="wrap">
<div class="footer-row">
<p><strong>cms.fivepaths.com</strong> is a <a class="fp-link" href="https://fivepaths.com"><img src="https://cdn.fivepaths.com/brand/fivepaths/fivepaths-logo-white.svg" alt="" width="108" height="111">FivePaths</a> product.</p>
<p class="footer-copy">© 2026 FivePaths, LLC</p>
</div>
</div>
</footer>
</body>
</html>
|