From 25b924a9881f9a312d2384c4c9b9077f9e6e563a Mon Sep 17 00:00:00 2001 From: Olivier Gorzalka Date: Tue, 29 Sep 2026 17:00:55 +0200 Subject: [PATCH] docs: block themes in the pollora-theming skill and core guidelines Block themes (Full Site Editing) are no longer ruled out: the skill documents where each file goes (templates/, parts/ and native patterns/*.php at the root, Blade patterns in resources/views/patterns), WordPress's pattern cache, the template-canvas marker, and the three pollora:make:theme templates, magazine (Buzz) included. --- CHANGELOG.md | 4 ++ resources/boost/guidelines/core.blade.php | 2 +- .../boost/skills/pollora-theming/SKILL.md | 49 +++++++++++++++++-- 3 files changed, 51 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 981ac54..5e0834c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **`pollora-theming` skill and core guidelines**: block themes (Full Site Editing) are no longer ruled out. The skill documents them — `templates/` and `parts/` at the theme root, static patterns as native `patterns/*.php`, Blade patterns in `resources/views/patterns`, WordPress's pattern cache, the `template-canvas` marker — and lists the three `pollora:make:theme` templates, `magazine` (Buzz) included. Needs the Pollora beta that ships the `magazine` template + ## [1.2.0] - 2026-09-28 ### Changed diff --git a/resources/boost/guidelines/core.blade.php b/resources/boost/guidelines/core.blade.php index 15af43a..1a39a87 100644 --- a/resources/boost/guidelines/core.blade.php +++ b/resources/boost/guidelines/core.blade.php @@ -5,7 +5,7 @@ ### Architecture - **Laravel-first routing**: Custom routes in `routes/web.php` take priority over WordPress template hierarchy -- **Blade templates**: No PHP template files — use `.blade.php` views exclusively +- **Blade templates**: No PHP template files — use `.blade.php` views exclusively. The one exception is a block theme (Full Site Editing), whose `templates/*.html`, `parts/*.html` and `patterns/*.php` WordPress resolves itself (`pollora:make:theme` template `magazine`) - **DDD structure**: Framework modules use Domain/Application/Infrastructure layers - **Auto-discovery**: Components are registered automatically via PHP 8 attributes — no manual `register_post_type()` or `add_action()` calls needed diff --git a/resources/boost/skills/pollora-theming/SKILL.md b/resources/boost/skills/pollora-theming/SKILL.md index 9a2252b..75afb4a 100644 --- a/resources/boost/skills/pollora-theming/SKILL.md +++ b/resources/boost/skills/pollora-theming/SKILL.md @@ -1,6 +1,6 @@ --- name: pollora-theming -description: Develop Pollora themes with Blade templates, Vite asset bundling, Tailwind CSS, and WordPress block editor integration. +description: Develop Pollora themes with Blade templates or as Full Site Editing block themes, Vite asset bundling, Tailwind CSS, and WordPress block editor integration. --- # Pollora Theme Development @@ -16,7 +16,15 @@ Generate a new theme: php artisan pollora:make:theme my-theme ``` -This creates a complete theme at `themes/my-theme/` and auto-activates it. +This creates a complete theme at `themes/my-theme/` and auto-activates it. The command offers three templates: + +| Template | Repository | What it is | +|---|---|---| +| `default` | `pollora/theme-default` | Blade starter: Vite, Tailwind CSS | +| `ecommerce` | `pollora/theme-apiary` | WooCommerce storefront, Blade + Alpine.js | +| `magazine` | `pollora/theme-buzz` | Full Site Editing block theme, see below | + +Skip the prompt with `--repository=pollora/theme-buzz` (any `owner/repo` works). ## Theme Structure @@ -199,6 +207,39 @@ return [ Roles resolve from common slugs (`primary`, `surface`, `foreground`, `outline`…). Modules and plugins can take over with the `pollora/login/palette`, `pollora/login/logo`, `pollora/login/styles` and `pollora/login/credit` filters. +## Block Themes (Full Site Editing) + +A theme can be a WordPress block theme instead of a Blade one: its templates are `templates/*.html`, edited in the Site Editor. Pollora renders it with no configuration — when no Blade view answers, its fallback lets WordPress resolve the block template itself, with the right HTTP status (a 404 answers 404, `error404` on ``). Generate one with the `magazine` template. + +One rule decides where a file goes: **the theme root holds what WordPress reads itself; `resources/views/` holds Blade.** + +``` +themes/my-journal/ +├── templates/*.html # Block templates (index, single, page, archive, search, 404…) — WordPress reads them +├── parts/*.html # Template parts (header, footer) +├── patterns/*.php # Static patterns, registered by WordPress itself +├── resources/views/patterns/*.blade.php # Patterns that need Laravel, registered by Pollora +├── theme.json # The design system; the build adds the @theme colours +└── style.css +``` + +- `templates/` and `parts/` must sit at the theme root: WordPress has no setting to move them. +- A static pattern is a native WordPress one: `patterns/*.php`, block markup under a docblock header (`Title`, `Slug`, `Categories`, `Inserter`, `Block Types`). WordPress reads **only `.php`** in `patterns/` — an `.html` there is silently ignored. The same layout the Site Editor exports. +- A pattern that needs Laravel (config, a helper, a computed value) is a Blade view in `resources/views/patterns/*.blade.php`, its header in a Blade comment: + +```blade +{{-- + Title: Colophon + Slug: my-journal/colophon + Categories: my-journal/patterns + Inserter: false +--}} +``` +- A template references a pattern with ``: templates stay thin, the markup lives in patterns. +- WordPress caches a theme's `patterns/` list: a new file appears once the cache is cleared (`wp eval 'wp_get_theme()->delete_pattern_cache();'`) or at once with `WP_DEVELOPMENT_MODE=theme`. +- Assets work as in any Pollora theme (`Asset::add(...)->useVite()`); a Vite entry is enqueued as a script module, after WordPress's import map. +- Don't add `Route::wp()` routes for pages the block templates render: a route answers first and bypasses them. + ## Debugging Templates With `WP_DEBUG` on, each page rendered through the template hierarchy says which template answered: @@ -210,9 +251,11 @@ curl -s https://site.test/some-page | grep pollora:template Responses from `Route::wp()` and Laravel routes carry no marker. +In a block theme the marker always reads `template="template-canvas"` (WordPress renders every block template through `wp-includes/template-canvas.php`): tell templates apart by the `` classes instead (`single-post`, `search-results`, `error404`…). + ## Important Notes -- **Never create WordPress PHP template files** — use Blade exclusively +- **Never create WordPress PHP template files** — use Blade exclusively. The exception is a block theme, whose `templates/*.html`, `parts/*.html` and `patterns/*.php` WordPress resolves itself (see Block Themes) - Theme providers in `app/Providers/` are auto-discovered - Design tokens (colours, font sizes, fonts, radii) go in the `@theme static` block of `app.css`, with concrete values; `wordpressThemeJson` writes them into the built `theme.json` the editor reads. Never `@import "tailwindcss" theme(static)` (it puts Tailwind's whole palette in the editor), never `var(--wp--preset--…)` inside `@theme` (a cycle once copied) - The root `theme.json` is the base: layout, spacing, `fontFace`, editor settings. A slug defined there wins over `@theme`; a whole family can be taken out of the generation with `disableTailwindColors` / `disableTailwindFontSizes` / `disableTailwindFonts` / `disableTailwindBorderRadius`