Skip to content

Sections & fields

SEK has a small vocabulary, and four words carry most of it: section type, section, field type, and field. The distinction in each pair is the same one: a reusable definition versus a placed instance that carries values.

A section type is a definition. It is the blocks/<handle>.yaml config plus its template: a named, reusable kind of section (a hero, a testimonial, a pricing table). It lives in your theme, in git, and it declares what fields the section type has and how it renders. It carries no content of its own.

A section (a section instance) is one placement of a section type on a page, with values filled in. Add the promo section type to a page twice and you have two sections: same definition, different headlines. Their values are stored in that page’s _sek_data; the definition they share stays in promo.yaml.

One hero.yaml (section type) → many hero sections across many pages, each with its own headline and image.

Section instances can nest. A section type whose config uses a children or sections field can contain other sections, to arbitrary depth: a layout section holding columns, each column holding content sections. There is no fixed “place sections live”; they live wherever the config puts them.

In the editor, a page’s section instances stack as a list of cards. Each row below is one instance of a section type, with its own values:

The SEK editor’s section list with several configured sections stacked in order, collapsed to their title rows.

And on the front end, a section instance renders through its section type’s template with its own values filled in. Here’s a hero section instance rendered live:

The Fieldwork demo page rendered live on the free showcase: the hero section near the top of the page.

A field type is a reusable kind of input: text, wysiwyg, image, select, link, and so on. Each field type knows how to render its editing UI, what shape of value it stores, and what config options it accepts. There are 43 field types at the time of writing (the definitive list is generated from source in the field-types catalogue: treat that as the count, not any number frozen into prose here).

A field is one entry in a section type’s fields: list: a specific use of a field type, with its own label, handle, and options. The promo section type from the walkthrough has two fields, a headline of type text and an intro of type wysiwyg:

fields:
- label: Headline
handle: headline
type: text # ← field type
- label: Intro
handle: intro
type: wysiwyg # ← field type

headline and intro are the fields; text and wysiwyg are their field types. The handle is how a field’s value is addressed everywhere: the template reads $data['headline'], and reconciliation matches saved values to config by handle.

Putting both pairs together:

Definition (in git) Instance (values in the database)
Section type: promo.yaml Section: a promo section on the About page
Field type: text Field: the headline on that section

The definitions are versioned code; the instances are content. Keeping those two apart is what lets SEK treat config as the source of truth and recover gracefully when a definition changes: see reconciliation and lost values.