{"url":"https://xstate.com/blog/content-negotiation","title":"One URL, three formats: this blog answers to the Accept header","summary":"Every post is HTML for people, and Markdown or JSON for agents, at the same address.","date":"2026-11-17","updated":null,"author":"xstate","tags":["agents","web"],"minutes":3,"markdown":"https://xstate.com/blog/content-negotiation.md","content_markdown":"More and more of the readers of a page like this one are not people. They are agents: Claude, Codex or Cursor\nlooking something up for someone, or a script that keeps a list of posts in sync. Those readers don't want our\nheader, our footer or the theme toggle. They want the words.\n\nSo every post on this blog is available in three formats at the same URL. A browser gets HTML. Anything that asks\nfor Markdown or JSON gets that instead.\n\n## Try it\n\n```bash\n# The page, as a browser sees it\ncurl https://xstate.com/blog/content-negotiation\n\n# The post as Markdown\ncurl -H 'Accept: text/markdown' https://xstate.com/blog/content-negotiation\n\n# The post as JSON: title, summary, date, tags, and the Markdown\ncurl -H 'Accept: application/json' https://xstate.com/blog/content-negotiation\n```\n\nThe same works for the changelog, and `/blog` with `Accept: application/json` returns the whole blog as a\n[JSON Feed](https://jsonfeed.org).\n\n## Files too, for tools that can't set headers\n\nSome tools fetch a URL and can't choose its headers. For them, each format also has its own address:\n\n| Format | Address |\n| - | - |\n| HTML | `/blog/<post>` |\n| Markdown | `/blog/<post>.md` |\n| JSON | `/blog/<post>.json` |\n| All posts | `/blog/feed.json` and `/blog/rss.xml` |\n| Changelog | `/changelog`, `/changelog.md`, `/changelog.json` |\n\nThe docs work the same way through their own files: `/docs/mcp` is the page and `/docs/mcp.md` is its Markdown. And\n[`/llms.txt`](https://xstate.com/llms.txt) lists every docs page and post with a link to its Markdown, so an agent can find what it\nneeds without crawling.\n\n## Browsers never notice\n\nThe rule is simple. If a request's `Accept` header includes `text/html`, it gets the page. Every browser sends\n`text/html`, so people always see the page they expect, and nothing changes for search engines.\n\nOnly a request that asks for JSON or Markdown and *not* HTML gets the other format. Those responses carry\n`Vary: Accept`, so a cache never serves one format to a reader who asked for another.\n\n## Getting Markdown right\n\nThe Markdown we serve is the file the post was written in, not HTML converted back. Converting a rendered page\nloses things: tables turn into runs of text, code blocks lose their language, and the navigation leaks into the\ncontent. Serving the source avoids all of that. We make two changes on the way out:\n\n- **The title and summary go on top**, followed by a line with the date, read time, tags and author. In the file\n  they live in frontmatter, which a reader shouldn't have to parse.\n- **Links become absolute.** In the file, a link to the docs is written `/docs/mcp`. Pasted into a conversation\n  with an agent, that path means nothing, so it becomes `https://xstate.com/docs/mcp`.\n\nThe JSON version carries the same Markdown in `content_markdown`, next to the fields a script would want on their\nown: `title`, `summary`, `date`, `updated`, `tags` and `minutes`.\n\n## Why bother\n\nAn agent that reads Markdown spends its context on the content instead of on markup, and gets the structure\n(headings, tables, code) intact. A script that reads JSON doesn't have to scrape. And people lose nothing: the\npage is still a page.\n\nWe build xstate for people who work with agents, so the site they read about it on should work for their agents\ntoo. The blog and changelog do today, the docs have Markdown files, and we'll bring the rest of the site to the\nsame rule."}