Skip to content

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.

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.

wp-content/themes/starterkit-classic/blocks/hero.yaml
label: Hero
handle: hero
templatePath: blocks.hero
category: content
icon: layout
description: 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).

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 are required, email, minLength, and maxLength; message overrides 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 URL
    handle: url
    type: url
    showWhen:
    field: linkType
    value: url

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: text

Notice 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).

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.

  • 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.