Deploy guide
How to serve the built site with nginx or Caddy, with correct MIME types, gzip, caching and the 404 page.
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
| Extension | Content-Type |
|---|---|
.html | text/html; charset=utf-8 |
.md | text/markdown; charset=utf-8 |
.txt | text/plain; charset=utf-8 |
.json | application/json |
.xml | application/xml or text/xml |
.css | text/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.