La receta de nginx

plasmoid incluye un bloque server de nginx documentado y listo para usar (deploy/nginx.conf en el repositorio). Apunta su root a tu salida de compilación, recarga nginx y listo: no se requieren ediciones por publicación.

Qué hace

• URL limpias. try_files $uri $uri/ $uri/index.html =404 convierte /1.2.0/en/guide/intro/ en el …/index.html renderizado.
• Resuelve los alias estables sin casos especiales. Como build emite /docs/ y /latest/ como alias de ruta reales, se resuelven a través del mismo manejador, y siguen funcionando a lo largo de los cambios de versión.
• 404 personalizado. Sirve el /404.html generado, o el /<locale>/404.html localizado cuando la petición está bajo un prefijo de locale (ver abajo).
• Descargas de archivos. Entrega /archive/*.zip con el tipo de contenido correcto.
• División de caché. Caché de larga duración para /assets/, corta para HTML para que las ediciones de documentación en sitio se publiquen rápidamente.
• Endurecimiento. Deniega los archivos ocultos (dotfiles).

La forma

# En el contexto http {} (los conf.d/*.conf ya lo están): elige el 404 localizado por
# prefijo de URL; las rutas sin locale recurren al /404.html del locale por defecto.
map $uri $plasmoid_404 {
    default  /404.html;
    ~^/es/   /es/404.html;     # una línea por cada locale no-por-defecto que construyas
}

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; }
}

Páginas de 404 localizadas

build emite un /<locale>/404.html por cada locale más una raíz /404.html en el locale por defecto. El map de arriba selecciona la página localizada por prefijo de URL, así que un enlace roto bajo /es/… muestra la página de no encontrado en español mientras que todo lo demás (la portada, /assets/, /docs/) recibe la por defecto. Lista los locales que publicas — son estables entre versiones, así que a diferencia del antiguo ajuste de versión esto se configura una sola vez. El map debe vivir en el contexto http {}; los archivos conf.d/*.conf ya lo están, así que la receta tal cual funciona.

Agnóstico a la versión por defecto

No hay ningún ajuste $plasmoid_latest que actualizar en cada publicación. Eso solía ser necesario cuando los alias eran páginas de redirección; ahora son enlaces simbólicos reales (o copias), así que nginx simplemente los sirve. El único modo que todavía necesita un ajuste de reescritura es aliases = "redirect": consulta Alias.

Pruébalo localmente con Docker

El directorio deploy/test/ del repositorio ejecuta esta misma receta en un contenedor de nginx contra un sitio recién compilado, sin necesidad de instalar nginx localmente. También es como la propia CI de plasmoid valida la receta.

Notas

• HTTPS: añade tu listen 443 ssl http2; + certificados como de costumbre; la receta es la capa de enrutamiento, no un vhost completo.
• Precompresión: descomenta gzip_static on; si tu nginx tiene el módulo y precomprimes los activos de texto en el momento del despliegue.