From a41da32ec584a71e124f6ef57d6eaba4f055b079 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 6 May 2026 07:53:32 -1000 Subject: [PATCH] docs: add content-negotiation to known exceptions (Vercel platform limitation) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Vercel serves static files before evaluating rewrites, so Accept: text/markdown header-conditional rewrites never fire for pre-rendered pages. The practical agent experience is already good — llms.txt directive, , and .md URLs all provide agents with clear paths to markdown content. Co-Authored-By: Oz --- .../afdocs-audit/references/known-exceptions.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.agents/skills/afdocs-audit/references/known-exceptions.md b/.agents/skills/afdocs-audit/references/known-exceptions.md index dee3589..6889c20 100644 --- a/.agents/skills/afdocs-audit/references/known-exceptions.md +++ b/.agents/skills/afdocs-audit/references/known-exceptions.md @@ -2,6 +2,17 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or failures but are expected and intentional. When reporting audit results, classify these as "Allowlisted" rather than "Remaining." +## content-negotiation + +**Expected status**: fail +**Reason**: Vercel serves static files before evaluating rewrites. Since all doc pages are pre-rendered as static HTML, header-conditional rewrites (`Accept: text/markdown`) never fire — the CDN matches the static file first and returns HTML. Astro's `middlewareMode: 'edge'` also doesn't work because the edge function's `next()` forwards to `/_render`, which doesn't exist for static pages. +**Mitigation**: The practical agent experience is already good despite this check failing: +- The llms.txt directive on every page tells agents that `.md` URLs are available +- `` in `` provides a machine-readable signal +- Agents that read either of these (Claude Code, Cursor, OpenCode) get clean markdown +- The `.md` URL convention works for 92%+ of pages +**Action**: No fix available on Vercel's static hosting. Would require migrating to a platform where middleware runs before static file serving (e.g., Cloudflare Pages). Accept as a platform limitation. + ## content-start-position **Expected status**: fail or warn