Skip to content

Configuration reference

The exhaustive, tabulated shape of every config type SEK reads. For the how-to (building a section YAML file step by step), see Config & YAML reference; for per-field-type options see the field-types catalogue; for how these shapes become a validating JSON Schema see JSON-Schema notes. Every shape below is read straight from the plugin’s own TypeScript config types.

One section type: a YAML file under the theme’s sections directory.

Key Type Required Notes
label string Yes Shown in the add-section picker and the section header.
handle string Yes Stable identifier. Must match the config’s file basename and the runtime Section.handle for reconciliation to work.
templatePath string Only at root Dotted template path. Required for root-level sections; nested (children) sections omit it: they render inside their parent’s template.
category string Yes Grouping label in the add-section picker.
icon string No Lucide icon name shown next to the label.
image string No Thumbnail URL shown in the add-section picker.
description string No Short help text shown in the picker.
fields SectionConfigField[] Yes The section’s field list (below). [] is valid: a section with no configurable content.
migrations MigrationRule[] No See Per-section migration rules.

Every field entry, regardless of type, extends BaseFieldConfig:

Key Type Required Notes
label string Yes Display name above the input.
handle string Yes Key in Section.values at runtime; the reconciliation match key. Pattern ^[a-zA-Z_][a-zA-Z0-9_-]*$.
description string No Help text below the input.
validation ValidationRule[] No { type: 'required' | 'email' | 'minLength' | 'maxLength', message?, value? }, evaluated in order.
adornment { pre?, post? } No Icon/text rendered inside the input container, before and/or after.
showWhen { field: string; value: string | boolean } No Conditional visibility against a sibling field’s value. Hidden fields skip rendering and validation.
triggersPreviewRefresh boolean No Defaults to false. Forces a live-preview refresh on change.

Beyond this shared base, each type value narrows to its own type-specific properties (an options object, sibling keys like sections/fields/value, or nothing at all). See the field-types catalogue for the full, generated per-type breakdown, and the field-types guide for how to read one of those tables.

PageTypeConfig (what the editor actually receives)

Section titled “PageTypeConfig (what the editor actually receives)”

The root config object parsed from the <script data-config> JSON tag inside the editor’s mount point.

Key Type Required Notes
fields SectionConfigField[] Yes Root-level fields; one or more are typically type: 'sections'.
preview boolean No Whether live preview is enabled for this post type.
previewDebounce number No Debounce interval (ms) for preview updates.
migrations MigrationRule[] No Top-level (post-type) migrations, applied before any section-level ones.

PostTypeConfig (what’s authored in YAML)

Section titled “PostTypeConfig (what’s authored in YAML)”

The on-disk YAML shape under a theme’s postTypes directory: assembled into a PageTypeConfig at load time.

Key Type Required Notes
sections string[] Only in the flat form A list of section handles. Omit when using the nested fields form instead.
fields SectionConfigField[] Only in the nested form Same shape as PageTypeConfig.fields, for post types whose sections live inside tabs/sections wrappers.
preview boolean No Same as PageTypeConfig.preview.
previewDebounce number No Same as PageTypeConfig.previewDebounce.
migrations MigrationRule[] No Same as PageTypeConfig.migrations.

Describes a meta-field: the form an author fills out when adding a field of a given type to a section, not the runtime value the field produces.

Key Type Required Notes
label string Yes Name shown in the field-type picker.
handle string Yes Matches one FieldType union member, e.g. "post-object".
icon string Yes Dashicon identifier.
description string Yes One-sentence tooltip in the picker.
category string Yes Picker grouping category.
fields SectionConfigField[] Yes The configuration form itself.
Shape Meaning
{ from: string; to: string } Move the value at dotted path from to dotted path to.
{ from: string; delete: true } Remove the value at dotted path from.

See Per-section migration rules for the dotted-path scheme and how these rules are applied.