Skip to content

The .sek.yml theme opt-in

A theme is not usable by SEK until it opts in. That opt-in is a single file, .sek.yml, at the theme’s root: its presence and its two keys are all the plugin needs to discover a theme’s sections and post-type configs.

wp-content/themes/starterkit-classic/.sek.yml
postTypes: config/post-types
sections: blocks
Key What it points at
postTypes A directory of post-type config YAML files: one per post type, each declaring which sections that post type may use (plus post-type-level settings like preview/previewDebounce).
sections A directory ConfigLoader scans recursively for section type YAML files: see Config & YAML reference.

Both paths are relative to the theme root: the directory .sek.yml itself lives in. There’s nothing else in the file; no version key, no feature toggles, no per-post-type entry. A theme is either opted in (the file exists and both keys are present) or it isn’t.

That’s the theme-level opt-in, and it’s binary: nothing in between. A separate, per-post-type condition governs whether SEK actually takes over a given post type’s edit screen: even on an opted-in theme, SEK replaces the native editor for a post type only when a config resolves for it (a file matching that post type’s slug, or the main.yaml catch-all, covered next). A post type with neither keeps its native WordPress editor.

The two starter-kit themes point these keys at different conventions, and both are equally valid. .sek.yml doesn’t prescribe a directory layout, only that the plugin (and the CLI) can find it from these two keys:

# starterkit-classic (plain PHP): sections live at the theme root
postTypes: config/post-types
sections: blocks
# starterkit / Sage: sections follow the Blade view-finder convention
postTypes: config/post-types
sections: resources/views/blocks

Files under the postTypes directory map which sections are available to which post type. The file basename maps to the post-type slug (page.yaml → the page post type), and the plugin falls back to main.yaml when no post-type-specific file exists: this is why starterkit-classic’s page editor loads from config/post-types/main.yaml. A sections: list nested inside the config (however deep, typically under a tabs/sections field, as in the walkthrough) is an allowlist scoped to the active theme: only handles whose blocks/<handle>.yaml (or the Sage equivalent) actually exists resolve to anything.

Discovery is upward-searching, not fixed-path

Section titled “Discovery is upward-searching, not fixed-path”

Both the plugin and the sek CLI find .sek.yml the same way: starting from a working directory and walking upward through parent directories until a .sek.yml is found (or the filesystem root is reached, in which case commands fail with a clear “no .sek.yml found” error). For the CLI this means you can run sek add-section from anywhere inside the theme, not only its root. Every path the CLI then writes to is resolved relative to the directory .sek.yml was found in (the theme root), not relative to your current working directory.

A developer doesn’t have to hand-write the first .sek.yml. When no configuration is found, the Config Editor admin UI shows a one-time setup form (two text inputs, defaulted to resources/views/blocks and config/post-types) that writes the file and creates both directories (when DISALLOW_FILE_MODS is set, a notice to add the file by hand appears instead). That’s a convenience for getting started, not a different mechanism: the file it writes is the exact same two-key shape documented above, and everything after that point (config discovery, the CLI’s upward search) works identically whichever way the file was created.