Skip to content

docs: add content-negotiation to AFDocs known exceptions #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rachaelrenk merged 1 commit into from
May 6, 2026
+11 −0
Merged

docs: add content-negotiation to AFDocs known exceptions #28

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .agents/skills/afdocs-audit/references/known-exceptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
- `<link rel="alternate" type="text/markdown">` in `<head>` 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
Expand Down
Loading