Agent-Friendly Web

Deploy guide

How to serve the built site with nginx or Caddy, with correct MIME types, gzip, caching and the 404 page.

Updated

The build output in dist/ is plain files, so any static file server can host it. A small VPS with 4 GB of RAM is far more than enough. The repository includes a sample nginx config and a sample Caddy config in deploy/.

Copy the files

Build, validate, then copy dist/ to the server:

make clean all
rsync -a --delete dist/ server:/var/www/agent-friendly/dist/

Before building for production, set base_url in site.json to your origin. See the authoring guide for the rules.

MIME types and charset

ExtensionContent-Type
.htmltext/html; charset=utf-8
.mdtext/markdown; charset=utf-8
.txttext/plain; charset=utf-8
.jsonapplication/json
.xmlapplication/xml or text/xml
.csstext/css

The most common mistake is serving .md as application/octet-stream, which makes clients download it instead of reading it. A missing charset turns non-ASCII text into garbage.

nginx

deploy/nginx.conf is a server block for sites-enabled/. It relies on the stock http block that already includes mime.types. Do not add a bare types block at server level: it replaces the whole inherited MIME map and every file becomes application/octet-stream. Only the Markdown location overrides its type:

charset utf-8;
charset_types text/plain text/markdown application/json text/css application/xml;
gzip on;
gzip_types text/css text/markdown text/plain application/json application/feed+json application/xml;
etag on;
error_page 404 /404.html;

location / {
    try_files $uri $uri/ =404;
}

location ~ \.md$ {
    types {}
    default_type text/markdown;
    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;
    add_header Cache-Control "public, max-age=300" always;
}

An add_header inside a location discards every add_header inherited from the server level. So the shared headers (X-Content-Type-Options and Referrer-Policy) live in deploy/nginx-headers.conf, and every location that adds headers includes it. HTML responses also get a Link header that points to the Markdown copy:

location ~ \.html$ {
    include /etc/nginx/snippets/agent-friendly/nginx-headers.conf;
    add_header Cache-Control "public, max-age=300" always;
    add_header Link "<$uri.md>; rel=\"alternate\"; type=\"text/markdown\"" always;
}

Set server_name to your host and add TLS, for example with certbot.

Caddy

deploy/Caddyfile does the same in fewer lines. Replace :80 with your host name and Caddy enables HTTPS by itself.

:80 {
	root * /var/www/agent-friendly/dist
	encode gzip
	file_server
	header X-Content-Type-Options nosniff
	@md path *.md
	header @md Content-Type "text/markdown; charset=utf-8"
	@txt path *.txt
	header @txt Content-Type "text/plain; charset=utf-8"
	handle_errors {
		rewrite * /404.html
		file_server
	}
}

Caching

HTML, Markdown, text, JSON and XML files are cached for 5 minutes (max-age=300) and revalidated with ETags, so agents see changes quickly but repeat fetches are cheap. The stylesheet is cached for a day. Because URLs never change, you can raise these values if you deploy rarely.

For a local preview, make serve runs Python's built-in server on port 8000, and make smoke starts it briefly and checks status codes and content types.