Site blueprint
Site blueprint
How macanderson.com is built to be read by people and by AI agents, and how to build a site like it. Markdown twins, llms.txt, an MCP server, a guarded assistant, and an installable app.
This site is written for two kinds of readers: people, and the AI agents that read the web for them. Every choice below serves one of them, and most serve both. Copy any of it.
Markdown#
Reading pages have a Markdown copy. Add .md to a page address, or send Accept: text/markdown at the normal address. Each copy links to the preferred HTML page. Markdown copies have noindex headers so search engines can focus on the HTML pages.
llms.txt and llms-full.txt#
/llms.txt is a short map of the site in the llms.txt format: who Mac is, then a link and a one-line description for every page. /llms-full.txt holds the whole site in one file, so an agent can load all of it in one request.
MCP server#
The site runs a Model Context Protocol server at https://macanderson.com/mcp. It is read-only and needs no key. Its tools search the site, read any page as markdown, list the field manual and research, and return Mac's profile and GitHub activity. To add it to Claude Code:
claude mcp add --transport http macanderson https://macanderson.com/mcp
In browsers that support WebMCP, the page also registers its tools with the browser, so an agent in the tab can search and open pages without scraping them.
Structured data#
Pages carry schema.org data that describes their content. The home page identifies Mac as a Person with his public profiles. Books list their chapters. Articles identify authors, dates, and images. The research index lists its essays and guides. Search engines can read these facts alongside the page text.
Assistant#
The assistant answers questions about Mac and his work. It follows the method the field manual teaches: decide in code what code can decide, and spend the model last.
- Code finds the passages first. A keyword index (BM25) ranks passages from the site's own pages before any model call. The same question always gets the same passages.
- The model sees only those passages, under a fixed token budget. It is told to answer from them and to say so when they do not cover the question.
- Every answer lists its sources, so you can check it.
- Limits sit in code, not in the prompt. Each question has a length cap. Each network address has a request limit. The whole site has a daily cap, and Vercel BotID screens out automated traffic. The assistant has no tools that write anything.
- When the model is unavailable or a limit is reached, the assistant still answers with the best matching passages and links.
Offline reading#
The site is a progressive web app. On a phone, add it to your home screen and it opens full screen with its own icon. A service worker keeps the pages you have read available offline.
Rendering#
Most reading pages are built ahead of time. The home and Work pages refresh GitHub activity through a cache. Server routes handle the assistant, subscriptions, admin sign-in, short links, and MCP requests. Fonts load from the same domain. Animations use the browser's scroll and view timelines and stop when your device asks for reduced motion.
Site setup#
Keep writing in plain files and build it into HTML and Markdown. Store shared facts, such as the author's name and public profiles, in one place. Add a sitemap and link related pages so readers can find them. An MCP server and an assistant can make the same writing available through tools.