Templates and layouts
Templates are reusable pieces of Twig markup, layouts wrap your pages in a shared header and footer, and the editor tells you where each page's CSS and JavaScript actually come from.
What they are
Templates are posts of the Templates type (wpcanai_template). Each one has a template type that decides when CanAI uses it:
- Composition pieces:
layout,header,footer,component. - Archives:
category,tag,author,search,404,archive. - Singles:
single-post. - WooCommerce (when active):
shop,product,product-category,product-loop,cart,checkout,my-account,order-received, plus the account endpoints. See WooCommerce.
A layout is a template of type layout. It holds the page shell (head, header, footer) and prints the page's own markup where it says {{ page_content }}. Pages and templates choose a layout in the CanAI Layout box; if they choose none, the Default Layout applies (CanAI → Settings, section "Default Layout"). A page with no layout and no default layout renders on its own.
A delegate page is for structural templates (shop, product-category, cart, checkout, my-account, order-received, category, tag, author, search, archive). The template can name a page whose layout and content it should use. The Delegate Page dropdown only appears for those types.
Use a layout whenever two or more pages share chrome. Put shared CSS and JavaScript on the layout so it is loaded once for every page that uses it.
Where you edit
Templates and Twig pages are edited in the CanAI Editor box right on the normal WordPress edit screen (post.php). The standalone Tools → Editor page is still available. The editor has HTML, CSS, JavaScript and History tabs, plus Structure, Format and Codes Guide helpers. Side boxes cover Structure, CanAI Layout, Template Variables, Context and Compiled Tailwind.
Two special cases:
- WooCommerce products keep the WooCommerce screen. A product that already has CanAI markup gets an "Edit with CanAI" side box and a notice instead of being redirected.
- Block-authored pages stay in the block editor. See Blocks and charts.
History is CanAI's own snapshot list, not WordPress revisions.
Where the CSS and JS come from
An empty CSS tab on a header or component is normal: the styles for pages using it usually live on the layout. CanAI shows this so you do not have to hunt.
- The CSS and JavaScript tabs show a line count when they have content. When they are empty, a note names the layout that supplies the code and how many lines it has.
- The note also says how the code is delivered: layout code is enqueued in
<head>(CSS) or the footer (JS) for every page using the layout, while a nested template's code is emitted inline with its markup. - CanAI → All Templates has Layout and Code columns. A Code chip is yours; a muted chip with an arrow is inherited from a layout. Hover for the delivery detail. Use the With CSS, With JS and Inherit only views to filter, and the search box also looks inside the CSS and JS.
Order of resolution for a page or template: its own code, then its layout (explicit choice, otherwise the Default Layout), then that layout's own parent layout.
Example
Create a layout, a page template, and ask an agent which styles reach the page.
{# layout (type: layout) #}
<!doctype html>
<html {{ language_attributes() }}>
<head>{{ wp_head() }}</head>
<body class="{{ body_class() }}">
<header>{% for item in get_menu('primary') %}<a href="{{ item.url }}">{{ item.title }}</a>{% endfor %}</header>
<main>{{ page_content }}</main>
{{ wp_footer() }}
</body>
</html>
Over MCP:
{ "ability": "wpcanai/create-template",
"input": { "title": "Site layout", "type": "layout", "html": "...", "css": "main{max-width:72rem}" } }
{ "ability": "wpcanai/read-meta",
"input": { "post_id": 42, "fields": ["asset_sources"] } }
create-template also accepts layout (a layout post ID) for non-layout templates. read-meta with asset_sources returns, in output order, each post that contributes CSS or JS (post_id, title, role, kind, lines, delivery). Roles are self, layout, parent_layout and default_layout.
In wp-admin: CanAI → All Templates → Add New, pick the type, open the CanAI Editor box, then choose a layout in CanAI Layout.
If something looks wrong
Run CanAI → Tools → Diagnostics, or the wpcanai/scan ability, which reports:
broken_layout- the chosen layout no longer exists.no_layout/no_layout_tpl- nothing wraps the page, or the layout template is missing.delegate_mismatch- a structural template's declared delegate page does not match.template_ok/template_body_ok- informational: the template is wired up.twig_syntax_error- the markup does not compile (see Authoring with Twig).
Other common causes:
- Styles seem missing on a component. Check the CSS tab note; the styles may be on the layout, or the page may be using a different layout than you think.
- Page content does not appear. The layout must print
{{ page_content }}. - Pointing at a deleted layout does not fall back to the Default Layout. Choose another layout or clear the field.