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.
The file
Section titled “The file”postTypes: config/post-typessections: 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 rootpostTypes: config/post-typessections: blocks# starterkit / Sage: sections follow the Blade view-finder conventionpostTypes: config/post-typessections: resources/views/blocksPost-type configs
Section titled “Post-type configs”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.
Bootstrapping one from the admin UI
Section titled “Bootstrapping one from the admin UI”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.
Where to go next
Section titled “Where to go next”- .sek.yml reference: the exhaustive reference entry for this file.
- The
sekCLI: scaffolding new sections and post-type configs once a theme is opted in. - Config & YAML reference: what goes
inside a section YAML file once
.sek.ymlpoints at its directory.