Support custom HTTP response headers (a _headers file) / Accept: text/markdown on GitHub Pages — for AI-agent readiness

[balat]

Problem

GitHub Pages serves every file with a fixed set of default headers and offers no way to add custom HTTP response headers (no _headers, no .htaccess, no config). This is a long-standing limitation (see #54257 and the CORS request in discussion 157852), and a new, concrete use case now makes it more pressing: making documentation sites readable by AI agents.

Emerging conventions for "agent-ready" sites (e.g. what isitagentready.com measures) rely on two HTTP-level signals that are impossible on a static host:

1. Link response headers advertising alternate representations, e.g.
   Link: </page.md>; rel="alternate"; type="text/markdown"
2. Markdown content negotiation: when a client sends Accept: text/markdown, return the Markdown variant of the same URL (with Vary: Accept).

Today the only workarounds are to put a CDN/proxy (Cloudflare, Netlify) in front of Pages, or to move off Pages entirely — which defeats the purpose of a zero-infra static host.

Proposal

Either (or both) of:

• A _headers file (same format as Cloudflare Pages and Netlify) so authors can attach custom response headers — including Link: — to path patterns. This single feature would also resolve the existing CSP/CORS requests.
• Built-in Accept: text/markdown content negotiation: when a sibling page.md exists next to page.html, serve it (with Content-Type: text/markdown; charset=utf-8 and Vary: Accept) to clients that request Markdown.

Why it matters

A huge share of open-source project documentation is hosted on GitHub Pages. Letting those sites become agent-ready — without forcing every maintainer onto a third-party proxy — would have outsized impact for the ecosystem, and it is squarely in line with GitHub's developer-tooling mission. The static assets (.md twins, llms.txt) are easy to publish today; only the HTTP layer is missing.

Prior art

Cloudflare Pages and Netlify already support a _headers file. Static Web Server has built-in Markdown content negotiation. Related community discussions: #54257 (custom/CSP headers on Pages) and the CORS-headers request.

[github-actions[bot]]

Thank you for your interest in contributing to our community! We currently only accept discussions created through the GitHub UI using our provided discussion templates. Please re-submit your discussion by navigating to the appropriate category and using the template provided.

This discussion has been closed because it was not submitted through the expected format. If you believe this was a mistake, please reach out to the maintainers.