Driver
The apexyard marketing site serves HTML only. Coding agents (Claude Code, Cursor, Aider, Cline) fetching a page for context pay the full HTML-chrome cost (navigation, footer, scripts, style tags). Per /generative-engine-audit 2026-05-20 finding G10, the GEO/AEO best practice is to ALSO serve a clean Markdown alternate at a predictable URL OR via an HTTP Link header — so agents fetch the lower-token version.
Medium severity. Not blocking but compounds — every coding-agent fetch is a measurable token saving once the alternates exist.
Scope
Two-part: serve markdown alternates AND advertise them.
1. Serve markdown alternates via Netlify rewrite
Add to site/_redirects (creates the file if it doesn't exist; bundles with #327 if that ticket is in flight):
/index.md /index.md.gen 200
/architecture.md /architecture.md.gen 200
/skills.md /skills.md.gen 200
*.md.gen files would be hand-written or generated at build time from the existing HTML. Since the marketing site has 3 pages, hand-written is fine for v1.
site/index.md.gen, site/architecture.md.gen, site/skills.md.gen — clean markdown versions of each page's content (no chrome). The lead from #TBD (GEO content-shape ticket) doubles as the markdown lead.
2. Advertise via HTTP Link header
Netlify headers via site/_headers:
/
Link: </index.md>; rel="alternate"; type="text/markdown"
/architecture.html
Link: </architecture.md>; rel="alternate"; type="text/markdown"
/skills.html
Link: </skills.md>; rel="alternate"; type="text/markdown"
Agents that read response headers (most do — it's cheap) discover the markdown route without an extra fetch.
3. Also add <link rel="alternate" type="text/markdown"> to each HTML's <head>
Belt-and-braces — some agents parse HTML for <link> tags but don't read response headers:
<link rel="alternate" type="text/markdown" href="/index.md">
Acceptance Criteria
Out of scope
- Auto-generating the markdown from HTML at build time (3 pages, hand-written is cheaper for v1)
- Markdown alternates for the
docs/ content (the framework's adopter docs, not the marketing site)
- A
/markdown route family — keep the /foo.md convention
Refs GEO-audit 2026-05-20T08-23-47Z finding G10 (persisted at projects/apexyard/audits/generative-engine-audit/)
Driver
The apexyard marketing site serves HTML only. Coding agents (Claude Code, Cursor, Aider, Cline) fetching a page for context pay the full HTML-chrome cost (navigation, footer, scripts, style tags). Per
/generative-engine-audit2026-05-20 finding G10, the GEO/AEO best practice is to ALSO serve a clean Markdown alternate at a predictable URL OR via an HTTPLinkheader — so agents fetch the lower-token version.Medium severity. Not blocking but compounds — every coding-agent fetch is a measurable token saving once the alternates exist.
Scope
Two-part: serve markdown alternates AND advertise them.
1. Serve markdown alternates via Netlify rewrite
Add to
site/_redirects(creates the file if it doesn't exist; bundles with #327 if that ticket is in flight):*.md.genfiles would be hand-written or generated at build time from the existing HTML. Since the marketing site has 3 pages, hand-written is fine for v1.site/index.md.gen,site/architecture.md.gen,site/skills.md.gen— clean markdown versions of each page's content (no chrome). The lead from #TBD (GEO content-shape ticket) doubles as the markdown lead.2. Advertise via HTTP
LinkheaderNetlify headers via
site/_headers:Agents that read response headers (most do — it's cheap) discover the markdown route without an extra fetch.
3. Also add
<link rel="alternate" type="text/markdown">to each HTML's<head>Belt-and-braces — some agents parse HTML for
<link>tags but don't read response headers:Acceptance Criteria
site/{index,architecture,skills}.md.genfiles exist with clean markdown content (no HTML chrome)site/_redirects(or equivalent Netlify config) serves/foo.md→/foo.md.gen(rewrite, not redirect)site/_headersadvertises the markdown alternate viaLinkheader on each HTML response<link rel="alternate" type="text/markdown">in its<head>curl https://yard.apexscript.com/index.mdreturns clean markdowncurl -I https://yard.apexscript.com/includes theLinkheaderOut of scope
docs/content (the framework's adopter docs, not the marketing site)/markdownroute family — keep the/foo.mdconventionRefs GEO-audit
2026-05-20T08-23-47Zfinding G10 (persisted atprojects/apexyard/audits/generative-engine-audit/)