-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Quick answers to common questions. If yours isn't here, open a discussion.
No. Obel is block-only. It supports the Cart, Checkout, Mini-Cart, Product Collection, and Product Filters blocks. It does not include classic PHP templates or shortcode-based cart/checkout pages.
If you have a plugin that hooks into the classic shortcode templates, it won't work on the cart/checkout. Check whether the plugin has block-template support before activating it on an Obel site.
Because every styling layer beyond theme.json becomes a place where a downstream developer has to hunt for the value to change. Two stylesheets means two source-of-truth conflicts. Five stylesheets means a guessing game.
theme.json is expressive enough for almost everything. The few cases where the block style engine can't express a layout (negative margins, complex form layouts), use the css escape hatch in theme.json itself. That keeps the source of truth single.
Patterns tend to be project-specific. The 11 patterns Obel ships are intentionally generic ("hero", "FAQ", "newsletter", etc.) and meant as starting points. Real shops should add their own patterns that match their brand and content needs.
Because:
- Build steps rot. The toolchain you pick today will be unmaintained in three years.
- The blocks that ship with WordPress 6.8+ and WooCommerce 10.0+ cover essentially every storefront UI need with built-in interactivity (Cart/Checkout, Mini-Cart, Accordion, Product Filters, Image Zoom).
- A theme without JS is faster, more accessible, and easier to maintain.
If you absolutely need custom JS, register a child theme that enqueues it. Don't add it to Obel itself.
Open Appearance > Editor > Styles in the WordPress admin to adjust colors, typography, and spacing visually. For deeper changes, edit theme.json directly. There is no other styling layer.
The Recipes page has step-by-step instructions for the 15 most common customizations.
In the framework: no. In a project clone: prefer to push the change into theme.json (either as a per-block style or via the css escape hatch on a block). If you absolutely must add CSS that isn't tied to a block, use Appearance > Editor > Styles > Additional CSS (which the user can edit through the admin).
Yes. Standard WordPress child theme rules apply. Create a child theme with style.css declaring Template: obel, and override any template, part, or pattern by placing a same-named file in the child. The child can also add JS, custom CSS, or anything else — but those additions aren't constrained by Obel's rules anymore (you're outside the framework).
Block-level styling lives in theme.json and applies sitewide. To change a block on one specific page only, use the editor: select the block, open the right sidebar, and override its color/spacing/typography there. The override is saved to the page content, not to theme.json.
In the framework: no. In a project clone: technically yes, but you'd defeat the purpose. Obel's design system already covers what those frameworks cover, in WordPress-native form. If you find yourself wanting Tailwind, you probably want a different theme.
In the WordPress admin, go to Appearance > Editor > Patterns > Header. The header part contains a core/site-logo block. Click it, upload your logo image, save. Done.
The logo appears in the header on every page. Size constrained via the block's width attribute (default 36px). To change globally, edit parts/header.html.
Python 3 is preinstalled on macOS and most Linux distros. Node requires either Homebrew or downloading an installer. Pure stdlib Python (no pip install) means the tooling works on any machine with Python 3.x without ceremony.
If you're on Windows without Python: install Python 3 from python.org and check "Add Python to PATH" during install.
No. They're a safety net. The theme will work without them. But if you want to ship a theme that passes the same standards as Obel itself, run python3 bin/check.py before each commit.
Yes. Edit bin/check.py and remove the offending entry from the results list in main(). But each check exists because someone hit the bug it catches. Removing one is a tradeoff.
Yes. The system prompt in SYSTEM-PROMPT.md is plain text. Paste it into Claude, ChatGPT, Cursor, Copilot CLI, Aider, Gemini, or anything else.
For Cursor specifically: AGENTS.md is automatically read.
No. The LLM can ask you to run them and paste the output back. python3 bin/check.py --quick is fast (<5 seconds offline) so the round-trip cost is low.
Push back on it. The hard rules in AGENTS.md are non-negotiable. If a request seems to require breaking one, the request needs to change, not the rule.
Yes. They're separate plugins that add new blocks and admin UI. Obel doesn't have specific styling for them, but they should render with default styles.
Use the Site Editor. Create a page, set it as the static front page, and build the layout using:
-
obel/hero-image(orobel/hero-text) for the hero -
obel/featured-productsfor the product grid -
obel/brand-storyfor the about section
Or copy the existing templates/front-page.html and modify it.
Check that the viewport is wider than the columns block's collapse breakpoint. The default core/columns block stacks to 1 column on mobile. To force 2 columns at all viewports, set isStackedOnMobile: false on the columns block.
Yes. Create templates/single-product-variable.html (for variable products) and templates/single-product-simple.html (for simple products). WordPress's template hierarchy will pick the more specific template based on the product type.
Probably not reliably. Obel uses templates and template slugs that are only canonical in WP 6.8+ and WC 10.0+. Below those versions, the cart and checkout templates may not load correctly.
Upgrade WordPress and WooCommerce first, then activate Obel.
Maybe. The theme code itself uses minimal PHP. But WooCommerce 10.x requires PHP 8.2, so you'd be limited by WC's requirements.
Should do. The wizard imports products and content into WooCommerce, which Obel then renders. Try it and report any issues.
Generally faster on first paint because there's no CSS file to fetch (all styles are inlined from theme.json). On subsequent loads, both are similar because the CSS is cached.
The biggest perf wins come from: serving images at the right size (use core/post-featured-image aspectRatio to constrain), enabling page caching at the WordPress level, and using a CDN for static assets. None of those are theme-specific.
Yes. WP Rocket, LiteSpeed Cache, W3 Total Cache, or even the host's built-in caching all work fine with Obel.
If your question isn't here, search the wiki, open a discussion, or read Architecture and Recipes — the answer is probably there.
Fifty on GitHub · Live demos · GPL-2.0-or-later · Block-only WooCommerce themes, zero CSS files, zero JS, zero build step