Config & YAML reference
A section type is declared entirely in one YAML file. The Config as source of truth and your first section walkthrough already covered the shape end to end for one small example; this page is the full reference to the format itself: every top-level key, how a field entry is built, and how nesting works.
Where a section config lives
Section titled “Where a section config lives”ConfigLoader discovers section YAML files recursively from the directory
named as sections in the theme’s .sek.yml
(blocks/ in starterkit-classic, resources/views/blocks/ in a Sage
theme). Every .yaml file it finds under that directory is a candidate
section type.
Top-level keys
Section titled “Top-level keys”label: Herohandle: herotemplatePath: blocks.herocategory: contenticon: layoutdescription: Full-bleed split hero: eyebrow + display headline + intro + one primary CTA, backdrop image opposite.
fields: - label: Headline handle: headline type: text validation: - type: required message: Headline is required
- label: Primary CTA handle: primaryCta type: link options: types: - url - page - anchor| Key | Required | What it does |
|---|---|---|
label |
Yes | Human-readable name shown in the editor’s add-section picker and section list. |
handle |
Yes | The stable identifier. Must match the file’s basename (hero.yaml → handle: hero): see Handles & Blade templates. |
templatePath |
Yes | Dotted path to the template that renders this section (blocks.hero → blocks/hero.php or the matching Blade view). See the render pipeline. |
category |
No | Groups sections in the add-section picker (e.g. content, heroes, layout). Purely organisational. |
icon |
No | Icon shown next to the label in the picker. |
description |
No | Short help text shown in the picker. |
fields |
Yes | The list of field entries: see below. An empty fields: [] is valid (a section with no configurable content). |
Field entries
Section titled “Field entries”Each item in fields: is one field. Every field entry shares the same base
shape regardless of type (label, handle, an optional description,
and optional validation), and then adds whatever config its type needs.
The full anatomy of that per-type config (the base shape shared by every
type, and the three shapes type-specific config can take) is
the field-types guide; this page covers
just the section-level wrapper around it.
fields: - label: Contact Email handle: email type: email validation: - type: required - type: email message: Please enter a valid email-
label: shown above the input in the editor. -
handle: the key the saved value is stored under in_sek_data, and the key the template reads ($data['email']). Must be unique within the section. -
type: which field type renders this field’s input and defines its config shape. -
validation: an array of rules, each{ type, message? }. The built-in rule types arerequired,email,minLength, andmaxLength;messageoverrides the default error text. -
showWhen: conditional visibility.{ field: <sibling handle>, value: <value> }hides this field unless the named sibling field currently holds that value. A hidden field is not rendered and is skipped by validation.- label: External URLhandle: urltype: urlshowWhen:field: linkTypevalue: url
Nesting: children and sections
Section titled “Nesting: children and sections”Some field types don’t hold a scalar value: they hold other sections.
children and sections fields declare a nested set of section types
directly inline, so one section type can compose smaller, reusable pieces:
- label: Tabs handle: tabs type: children multiple: true sections: - label: Tab handle: tab category: layout fields: - label: Title handle: title type: textNotice sections and multiple sit directly on the field entry, not nested
under an options: key: that’s one of the structural shapes covered in the
field-types guide. A nested section entry under sections: is itself a full
section definition (its own handle, fields, and so on): it just isn’t a
separate top-level YAML file. tabs and repeater fields nest the same way,
via their own fields: list.
This is also the shape the render pipeline descends: a template’s $data
for a children/sections/tabs field is an array or map of nested
instances, walked recursively by field-type discriminator rather than by any
fixed “depth” (see the render pipeline).
How config becomes an editor
Section titled “How config becomes an editor”Nothing about a section’s runtime editing UI is hand-wired. The React editor
reads the resolved config tree and, for every field entry, dispatches on
type to the matching field component (FieldRenderer’s component
registry) to render that field’s input. Change a field’s type in YAML and
the editor renders a different control on next load: there’s no separate UI
definition to keep in sync.
Where to go next
Section titled “Where to go next”- Field types: the full anatomy of per-type field config, with worked examples.
- The render pipeline: how this same config-plus-values pair reaches a template on the front end.
- Configuration reference: the exhaustive, generated reference for every key this page introduced.