The nginx recipe

plasmoid ships a documented, drop-in nginx server block (deploy/nginx.conf in the repository). Point its root at your build output, reload nginx, and you’re done — no per-release edits required.

What it does

• Clean URLs. try_files $uri $uri/ $uri/index.html =404 turns /1.2.0/en/guide/intro/ into the rendered …/index.html.
• Resolves the stable aliases with no special-casing. Because build emits /docs/ and /latest/ as real path aliases, they resolve through the same handler — and keep working across version bumps.
• Custom 404. Serves the generated /404.html, or the localized /<locale>/404.html when the request is under a locale prefix (see below).
• Archive downloads. Hands out /archive/*.zip with the right content type.
• Caching split. Long-lived caching for /assets/, short for HTML so in-place doc edits go live quickly.
• Hardening. Denies dotfiles.

The shape

# In the http {} context (conf.d/*.conf already qualifies): pick the localized 404
# by URL prefix; non-locale paths fall back to the default-locale /404.html.
map $uri $plasmoid_404 {
    default  /404.html;
    ~^/es/   /es/404.html;     # one line per non-default locale you build
}

server {
    listen 80;
    server_name docs.example.com;
    root /srv/www/plasmoid-site;     # the --site dir from build
    index index.html;

    location /assets/  { expires 30d; add_header Cache-Control "public"; try_files $uri =404; }
    location /archive/ { types { application/zip zip; } try_files $uri =404; }

    location / {
        expires 5m;
        add_header Cache-Control "public, must-revalidate";
        try_files $uri $uri/ $uri/index.html =404;
    }

    error_page 404 $plasmoid_404;
    location = /404.html { internal; }
}

Localized 404 pages

build emits a /<locale>/404.html for every locale plus a root /404.html in the default locale. The map above selects the localized page by URL prefix, so a broken link under /es/… shows the Spanish not-found page while everything else (the landing, /assets/, /docs/) gets the default one. List the locales you ship — they are stable across releases, so unlike the old version knob this is set once. The map must live in the http {} context; conf.d/*.conf files already are, so the shipped recipe works as-is.

Version-agnostic by default

There is no $plasmoid_latest knob to bump each release. That used to be necessary when the aliases were redirect pages; now they are real symlinks (or copies), so nginx just serves them. The only mode that still needs a rewrite knob is aliases = "redirect" — see Aliases.

Test it locally with Docker

The repository’s deploy/test/ directory runs this exact recipe in an nginx container against a freshly built site — no local nginx install needed. It’s also how plasmoid’s own CI validates the recipe.

Notes

• HTTPS: add your listen 443 ssl http2; + certs as usual; the recipe is the routing layer, not a full vhost.
• Pre-compression: uncomment gzip_static on; if your nginx has the module and you pre-compress text assets at deploy time.