Authoring with Twig
Pages and templates are written as Twig HTML with CSS and JavaScript alongside, styled with Tailwind, made interactive with Alpine.js, and decorated with Lucide icons.
What it is
Every CanAI page or template stores three fields: HTML (Twig), CSS and JavaScript. The HTML is rendered on the server with the WordPress-aware context for the current page. Use it when you want full control over markup and design; use the block editor route in Blocks and charts when owners should edit copy in Gutenberg.
In templates you get:
- Page data such as
post, archive data and, with WooCommerce, cart and customer data. A template can add more through its Context box (queries, options, menus). Developers can extend it with thewpcanai_template_contextfilter. - Helper functions, among them
wp_head(),wp_footer(),body_class(),bloginfo(),language_attributes(),media_url(),image_attrs(),id_url(),post_url(),the_content(),shortcode(),get_option(),breadcrumbs(),wpcanai_template()(include another template),wpcanai_chart(),get_menu(),t()andturl(). Menus and links are covered in Navigation and links, translation in Multilingual. - A Template Variables side box in the editor that lists what is available for the post you are editing.
Tailwind CSS classes just work. By default the Tailwind runtime is served from the plugin, with no CDN. For production an agent can compile a build that CanAI stores on the layout and prints inline in <head>, so pages skip the runtime compiler.
Alpine.js (x-data, x-show, ...) and Lucide icons (<i data-lucide="menu"></i>) are loaded when a page uses them. Load behaviour and source (plugin or CDN) are in CanAI → Settings.
The editor's Structure helper lists the page's landmarks from single-line Twig comments such as {# Section / Hero #} placed before each landmark. Use Twig {# #} comments, not HTML <!-- -->, which reach view-source. Format tidies the markup. CSS and JavaScript tabs behave as described in Templates and layouts.
Example
A card with Tailwind, Alpine and an icon:
{# Section / Hero #}
<section class="mx-auto max-w-3xl p-8" x-data="{ open: false }">
<h1 class="text-3xl font-bold">{{ post.post_title }}</h1>
<button class="mt-4 inline-flex items-center gap-2 rounded bg-blue-600 px-4 py-2 text-white"
@click="open = !open">
<i data-lucide="info"></i> {{ t('More details') }}
</button>
<p x-show="open" class="mt-4">{{ t('Everything you need to know.') }}</p>
</section>
Write it from an agent, with an optimistic lock so you never overwrite someone else's edit:
{ "ability": "wpcanai/read-meta", "input": { "post_id": 42, "fields": ["html"] } }
{ "ability": "wpcanai/write-meta",
"input": { "post_id": 42, "html": "...", "expected_hash": "<sha1 from read-meta hashes>" } }
To change a few words without resending the page, use wpcanai/replace-in-meta with {from, to} pairs.
The Tailwind build (Lighthouse & Production Optimization)
By default during development, CanAI serves an in-browser Tailwind runtime that JIT-compiles utility classes on page load. While convenient, running the runtime compiler in visitor browsers adds JavaScript execution time that can drag down Lighthouse scores (First Contentful Paint, Total Blocking Time, and LCP).
For best Lighthouse scores and production speed, precompile the Tailwind build. A precompiled build:
- Replaces the in-browser compiler with static, minified CSS printed inline in
<head>. - Completely eliminates runtime styling scripts, keeping visitor CPU work near zero.
- Ensures pages load instantly without any flash of unstyled content (FOUC).
Compiled output is cached on the post (_canai_tailwind_build, plus a hash and timestamp). Saving HTML, CSS or JS marks it stale; until it is recompiled pages quietly use the Tailwind runtime instead. The Compiled Tailwind side box shows Compiled, Compiled (stale), or "No compiled build on this page", with size, hash and build time.
How to compile
Ask your AI agent with commands like:
compile tailwindcssoptimize production/canai-mcp compile tailwindcss
The canai-mcp skill runs the "Compile Tailwind for Production" workflow, scanning the layout and connected templates. It compiles with Tailwind v3 (v4 compile silently drops responsive classes) and stores the result on the layout.
To compare against the runtime without touching the stored build, add ?wpcanai_tw=cdn to the URL (this request only), or use the bypass toggle in the Compiled Tailwind box (logged-in editors only).
If something looks wrong
- Run CanAI → Tools → Diagnostics (or
wpcanai/diagnostics) for server health: PHP version, required extensions, memory, writable folders. Therendergroup lists template warnings from the last 7 days. wpcanai/scanreportstwig_syntax_error,missing_structure_comment/invalid_structure_comment,leaky_commentandleaky_secret(an HTML comment or value that should not reach view-source),split_sentenceandunsupported_t_markup(translation text), andrender_warning(a PHP warning your Twig raised, with post, field and line; for example printing an array as text).wpcanai/read-metawithrender_warningsgives the same detail for one post. Writing that field clears its entries until the page renders again.- Responsive classes missing on a compiled build: it was compiled with Tailwind v4, so recompile with v3.
- Markup not saving: HTML is raw, so saving needs the
unfiltered_htmlcapability (on multisite, usually Super Admins only). - A
format_mismatcherror means the page is a blocks page; only CSS can be written to it directly.