Cache and Markdown
CanAI clears your page cache after it changes something, and can hand AI agents a clean Markdown version of any page it renders.
Page cache
If a supported cache plugin is active, CanAI purges it for you whenever CanAI writes a template, a snippet or a page. That covers the editor, MCP writes, imports and preset installs. You do not need to clear the cache by hand after an edit.
Supported plugins: LiteSpeed Cache, WP Rocket, W3 Total Cache, WP Super Cache and WP-Optimize. CanAI uses the first one it finds. With none active, nothing is purged and nothing errors.
- A template or snippet change purges every page.
- A page change purges that page.
- The purge runs once per request, after the response is sent.
Turn it off or on
Go to CanAI → AI Client → Guardrails → Page cache. The box "Purge the page cache after CanAI writes" is on by default, and the section says which cache plugin was detected. Agents can flip it with wpcanai/update-settings (key wpcanai_purge_after_write, true or false).
Purge on demand
wpcanai/purge-cache clears the cache outside a CanAI write, for example after you changed something in another plugin.
{ "scope": "all" }
{ "scope": "url", "target": "https://example.com/about/" }
{ "scope": "post", "target": 123 }
url must be on this site. post takes a post ID and also clears WordPress's own post cache. The reply is {purged: [{scope, target}], plugin, note}. plugin is null when no cache plugin is active, which is not an error.
The purged key
Write tools such as wpcanai/write-page or wpcanai/import end their reply with purged. It looks like {scope: "post", plugin: "wp-rocket"}, or is null when nothing was purged (no cache plugin, or the setting is off).
Markdown for agents
When a client asks for Markdown, CanAI answers with the page content converted to Markdown instead of the full HTML document. Browsers never see a difference.
An agent asks in either of two ways:
curl -H "Accept: text/markdown" https://example.com/about/
curl "https://example.com/about/?format=markdown"
An Accept header only counts when it names text/markdown and ranks it above text/html; */* does not trigger it. The reply carries a short front-matter block (title, description, canonical, updated, image where known), the converted body, Content-Type: text/markdown, and X-Markdown-Tokens / X-Original-Tokens size hints. Normal HTML pages advertise the Markdown version with a Link header and a <link rel="alternate" type="text/markdown"> tag.
Markdown is only served for GET and HEAD requests on pages CanAI renders (Twig or blocks pages, and posts rendered through a single-post style template). The cart, checkout and My Account pages always stay HTML, as do password-protected pages and 404s.
Caching: a Markdown reply chosen by the Accept header is marked uncacheable so a cache never hands it to the next browser. The ?format=markdown address is its own cache key and caches normally.
Turn it off
CanAI → Settings → Markdown for agents, untick "Serve the page content as Markdown to agents that ask for it", then Save Markdown Settings. It is a site-wide switch. Agents can use wpcanai/update-settings with wpcanai_markdown_negotiation.
Adjust the output (developers)
Filters: wpcanai_markdown_enabled (veto per post), wpcanai_markdown_source_html, wpcanai_markdown_front_matter and wpcanai_markdown_output. To support a cache plugin CanAI does not know, use the wpcanai_page_cache_adapter filter.
If something looks wrong
- Edits don't show on the live page. Check Guardrails → Page cache: is a plugin detected, and is the box ticked? If the setting is on and nothing is detected, run
wpcanai/purge-cacheor clear the cache in your host. Host or CDN caches are outside CanAI's reach. purge-cachereturnsplugin: null. No supported cache plugin is active. For scopepostonly WordPress's post cache was cleared (seenote).invalid_input.scopemust beall,urlorpost, andurlneeds a full URL on this site.invalid_post.targetfor scopepostmust be an existing post ID.- Agents get HTML. Check the Markdown switch, that the page is one CanAI renders, that it is not cart/checkout/My Account, and that the
Acceptheader namestext/markdown. A host or CDN that rewritesAcceptcan defeat it; use?format=markdown. - Page caches serve stale pages for full-page templates. CanAI renders the complete document and ends the request early, so aggressive caches may skip or hold old copies. Exclude those URLs in the cache plugin, or purge after editing.