Strong foundation, undiscoverable strengths
The infrastructure is excellent and the hardest feature is already built: nearly every English guide is served as clean Markdown at a .md/ URL. The problem is that nothing tells an AI agent this exists. The two weakest categories are almost entirely last-mile wiring on top of infrastructure you already run, which makes the score cheap to move.
cy_llm_widget tag that shows this was built on purpose. Yet no directive, no content negotiation, and no llms.txt link points agents to it. They fetch the heavy HTML and never benefit from the Markdown you already generate.
Score by category
Seven categories from the Agent-Friendly Documentation Spec. Bars animate on load.
What is already right
Clean Markdown, served natively
Every leaf guide answers on <slug>.md/ with Content-Type: text/markdown. Verified across the full set. Frontmatter carries title, subtitle, and source.
Server-rendered
WordPress plus WP Rocket plus Cloudflare. No JavaScript execution needed to read content, so every agent sees the full page.
Small and front-loaded
Markdown median about 5K characters, all pages well under limits, content starts within the first 3% of the page.
Stable and open
Stable URLs, correct error codes, no auth gates. robots.txt allows AI crawlers and declares the sitemap.
All 307 individual doc pages
Every /documentation/ guide in the sitemap was fetched and checked for HTTP health and for a working Markdown version at its .md/ URL. Filter and search the complete set below.
Markdown coverage by locale
| Locale | Pages | Markdown OK | Coverage |
|---|
English is at 99%. Every non-English locale is effectively 0%, which is the single biggest slice of the defect list.
Per-page results
| Page | Locale | HTML | .md | Status |
|---|
What each status means and how to fix it
Ready
HTML 200 and the .md/ URL returns 200 as text/markdown. Fully agent-ready, nothing to do. (290 pages)
Markdown missing
HTML 200 but .md returns 404, so the page has no markdown twin. All 13 are non-English locales. Fix: extend the .md rewrite and the cy_llm_widget export to /{locale}/documentation/ paths, or stop advertising markdown for them.
Markdown broken
HTML 200 and .md returns 200, but as text/html instead of markdown. The route answers yet silently serves the full HTML page, so a naive "does .md return 200?" check passes while agents get ~156 KB of HTML mislabeled as markdown. Fix: regenerate the markdown for these posts (the generator likely choked on their content, such as code samples) and add a CI assert that .md is text/markdown. (2 pages)
Page dead
HTML returns 404 though the URL is still in post-sitemap.xml. Fix: restore the page or remove it from the sitemap so crawlers and agents stop hitting dead links. (2 pages)
WordPress vs Strapi / Next.js
The site is mid-migration from WordPress to a Next.js frontend (Strapi headless CMS). Stack was fingerprinted per page via _next/ and vary: rsc (Strapi/Next) versus wp-content and Yoast (WordPress). The split decides which team owns each fix.
Strapi / Next.js
Home, Pricing, Features, About, compliance pages (e.g. CCPA), Knowledge Base, and the FAQ landing. Server-rendered, but no .md markdown on any of them.
WordPress
Docs hub, every /documentation/ guide (including /documentation/faq/ answer articles), the blog, product and free-tool pages. This is where the clean .md markdown already exists.
Which stack owns each issue
| Issue | Owner |
|---|---|
Clean .md markdown already works | WordPress only |
llms.txt plus broken nested /blog/ and /documentation/ llms.txt (404) | Strapi / Next.js |
| No markdown and no content negotiation on marketing, FAQ, KB | Strapi / Next.js |
13 localized guides missing .md; 2 silent .md failures | WordPress |
| Dead sitemap URLs (404) | Migration mismatch: Yoast sitemap vs Next routing |
FAQ section: 70 / 100 (C)
/category/documentation/faq/ is served by Strapi/Next and is server-rendered, so agents can read it, but it scores 0 on Markdown Availability: no .md version and Accept: text/markdown is ignored. The HTML is 379 KB (96% boilerplate), and there is no llms.txt directive.
8 FAQ subcategory URLs are hard 404
Listed in the sitemap, no redirect, dead on the Next.js frontend. Restore the routes or drop them from the sitemap.
/category/documentation/faq/account/
/category/documentation/faq/cookie-banner/
/category/documentation/faq/data-collection/
/category/documentation/faq/faq-features/
/category/documentation/faq/faq-integrations/
/category/documentation/faq/hubspot/
/category/documentation/faq/pricing/
/category/documentation/faq/wix/One FAQ article dead on Next.js
/documentation/faq/wix/brand-logo-to-consent-banner/ returns HTML 404 while its WordPress .md still resolves. Working FAQ articles (WordPress, with markdown): the two HubSpot guides.
What is costing points
Markdown is undiscoverable
No agent-facing directive in the HTML or Markdown of any page, the server ignores Accept: text/markdown and returns HTML, and every llms.txt link points to HTML rather than the .md variant. Agents default to the heavy HTML path.
Two advertised nested llms.txt files return 404
The root llms.txt points agents to six per-section indexes. /knowledge-base/, /infographics/, /partners/case-study/ and /partners/blog/ resolve, but /blog/llms.txt and /documentation/llms.txt both 404, the two that matter most. The docs link also points at /documentation/ while the real docs live under /category/documentation/.
llms.txt indexes a small fraction of the docs
The root llms.txt lists documentation category pages but almost none of the 290-plus individual guides. Agents relying on it as the map miss most of the actual content.
llms.txt is missing its summary blockquote
The file parses and has an H1, but there is no > blockquote summary directly under the title. That is the first line agents read. One-line fix.
Category and index pages have no Markdown
/category/documentation/ and its subcategories return 404 on .md. Only leaf guides have Markdown, so an agent landing on a section index cannot get a clean version of it.
Prioritized action steps
Ordered by impact against effort. Steps 1 to 4 move the score; steps 5 to 7 clean up the per-page defects found in the full validation. Every snippet is copy-paste ready.
Announce the Markdown on every doc page
Add an alternate-format link plus a visually-hidden directive to the head of doc pages, so agents learn the .md/ version and the index exist. Drop into your theme's functions.php.
add_action( 'wp_head', function () {
// Scope to documentation guides only.
if ( ! is_singular( 'post' ) || strpos( $_SERVER['REQUEST_URI'], '/documentation/' ) === false ) {
return;
}
$md = rtrim( get_permalink(), '/' ) . '.md/';
printf( '<link rel="alternate" type="text/markdown" href="%s">' . "\n", esc_url( $md ) );
printf(
'<div style="position:absolute;width:1px;height:1px;clip:rect(0 0 0 0);overflow:hidden">'
. 'For AI agents: a Markdown version of this page is at %s. '
. 'Full documentation index: <a href="https://www.cookieyes.com/llms.txt">llms.txt</a>.'
. '</div>' . "\n",
esc_url( $md )
);
}, 1 );Honor Accept: text/markdown (content negotiation)
You already have the .md/ rewrite. Route agents that request Markdown to it. As a Cloudflare Worker, since you already front the site with Cloudflare.
export default {
async fetch(request) {
const url = new URL(request.url);
const accept = request.headers.get('Accept') || '';
const wantsMd = accept.includes('text/markdown');
const isDocPage = url.pathname.startsWith('/documentation/') && !url.pathname.endsWith('.md/');
if (wantsMd && isDocPage) {
url.pathname = url.pathname.replace(/\/$/, '') + '.md/';
return fetch(new Request(url, request));
}
return fetch(request);
}
}Repair and align the nested llms.txt files
Generate /blog/llms.txt and /documentation/llms.txt with the same mechanism that produces the four working ones, or repoint the root links to the real locations. Resolve the /documentation/ versus /category/documentation/ mismatch so the advertised path serves the docs index.
Expand llms.txt coverage, point links to .md, add a summary
Regenerate llms.txt from the sitemap so all guides are indexed, write each link as its .md/ variant, and add the one-line summary blockquote under the H1.
# CookieYes - Cookie Compliance Made Easy
> CookieYes is a Google-certified consent management platform used by 1.5M+ websites to comply with GDPR, CCPA, LGPD and other privacy laws via cookie banners, automatic scanning, and consent logging. This index links to product, documentation, and support resources.
## Documentation Guides
- [Add a cookie banner on WordPress](https://www.cookieyes.com/documentation/cookie-banner-wordpress.md/)
- [Install & set up CookieYes on Shopify](https://www.cookieyes.com/documentation/how-to-install-and-setup-cookieyes-shopify.md/)
- [Cookie banner on React](https://www.cookieyes.com/documentation/cookie-banner-on-react-js.md/)
- [Content Security Policy](https://www.cookieyes.com/documentation/content-security-policy.md/)
- ...generate the rest from post-sitemap.xmlFix the two silent Markdown failures
These two English guides return HTTP 200 at their .md URL but serve HTML, not Markdown, so an agent thinks it received Markdown and gets the heavy HTML instead. Regenerate their Markdown export.
https://www.cookieyes.com/documentation/custom-data-layer/
https://www.cookieyes.com/documentation/how-to-prevent-fetch-and-xmlhttprequest-overrides-in-cookieyes/Remove or fix the two dead sitemap URLs
These are listed in post-sitemap.xml but the HTML returns 404. Either restore the pages or drop them from the sitemap so crawlers and agents stop hitting dead links.
https://www.cookieyes.com/documentation/accessiyes-accessibility-widget/customising-accessiyes-via-javascript/
https://www.cookieyes.com/documentation/faq/wix/brand-logo-to-consent-banner/Extend Markdown to localized and category pages
All non-English guides (de, es, fr, it, nl, pl, sv) return 404 on .md, and section index pages under /category/documentation/ do too. Apply the same rewrite and export that powers English leaf guides to these paths.
Re-run the audit
Deterministic sampling gives reproducible results so you can confirm each fix. The second block is the exact per-page Markdown check used for this audit; drop it into CI.
npx afdocs check https://www.cookieyes.com/category/documentation/ \
--format scorecard --sampling deterministic --fixes \
--llms-txt-url https://www.cookieyes.com/llms.txt# Fail if any English guide does not serve real Markdown at its .md/ URL
curl -s https://www.cookieyes.com/post-sitemap.xml \
| grep -oE 'https://[^<]+/documentation/[^<]+' \
| grep -v '/[a-z][a-z]/documentation/' \
| while read u; do
ct=$(curl -sIL -o /dev/null -w '%{http_code} %{content_type}' "${u%/}.md")
case "$ct" in
"200 text/markdown"*) ;;
*) echo "MARKDOWN ISSUE: $u -> $ct" ;;
esac
done