Cómo se publica un sitio

Un sitio pasa por cuatro fases. Solo la última cambia lo que ven los visitantes.

Borradores y revisiones

El borrador es el estado actual de los archivos del sitio. Cada cambio crea una revisión: un id de commit de Git de 40 caracteres, con un resumen de una frase y el autor (el editor, el asistente, un agente a través de MCP, la CLI o la API). No se borra nada: el historial muestra todas las revisiones, y puedes comparar dos de ellas o restaurar una anterior como una nueva entrada.

Un cambio equivale a una revisión, independientemente de los archivos que afecte. Una llamada que modifica tres archivos crea una sola entrada, y un cambio repartido entre varias llamadas utiliza un changeset que se confirma una sola vez. Un changeset permanece abierto durante 10 minutos.

Dos personas escriben a la vez

Al modificar un archivo, envía el hash que has leído (expected_hash). Si alguien ha modificado ese archivo desde entonces, se rechaza el cambio completo con 409 conflict, no se escribe nada y el error de REST o CLI incluye la revisión actual:

{
  "error": {
    "type": "conflict_error",
    "code": "conflict",
    "message": "...",
    "details": {
      "reason": "revision_conflict",
      "current_revision": "9f2c...",
      "paths": [
        { "path": "src/content/site/business.json", "expected": "a1b2...", "found": "c3d4..." }
      ]
    }
  }
}

Vuelve a leer los archivos indicados en paths, aplica el cambio sobre ellos e inténtalo de nuevo. En MCP, el error indica que el sitio ha cambiado desde que se preparó la edición, sin details, así que tendrás que volver a leer los archivos. Los endpoints de contenido leen el hash actual por su cuenta, por lo que solo se produce un conflicto si alguien escribe exactamente en el mismo momento.

Compilaciones

Una compilación genera un sitio estático a partir del borrador o de una revisión que indiques. Se ejecuta en un contenedor aislado, sin conexión a la red ni credenciales, y se detiene al cabo de 5 minutos. Una compilación pasa por los estados queued, building y collecting hasta llegar a ready, o termina como failed o cancelled. Si inicias una compilación de una revisión que ya tiene una compilación lista, se devuelve esa en lugar de volver a compilarla.

Si una compilación falla, error indica el motivo y el registro de compilación muestra la salida del compilador. Corrige los archivos y vuelve a compilar.

Vistas previas

Una vista previa es un enlace privado a una compilación, válido durante 7 días por defecto y hasta 30 como máximo. Cualquier persona con el enlace puede ver esa compilación sin tener una cuenta. El enlace no da ningún otro acceso, nunca se indexa y se puede revocar. Muestra el aspecto que tendría el sitio, así que compártela antes de publicar.

Una vista previa no es un sitio publicado. Todas las páginas incluyen una pequeña cinta de «Vista previa» (oculta mientras editas en la aplicación) y se ejecutan en un entorno aislado con el origen null. Sus scripts no pueden establecer cookies, usar el almacenamiento del navegador ni iniciar un Worker. Si una API externa rechaza ese origen, bloqueará su funcionamiento, por lo que los formularios, los avisos de cookies y las herramientas del lado del cliente que necesiten esas funciones solo funcionarán cuando se publique el sitio. Una advertencia de compilación indica cuáles utiliza tu sitio.

Publicación

Al publicar, una compilación pasa a ser lo que ven los visitantes en todas las direcciones del sitio, en aproximadamente un minuto. Es la única fase que modifica el sitio público.

1. Revisa. review_publish muestra qué compilación se publicaría, si corresponde al borrador más reciente, qué impide publicarla y un expected_generation.
2. Publica esa compilación con el expected_generation que has consultado.

La generación es un contador que aumenta con cada publicación, reversión y anulación de publicación. Al enviarlo de vuelta, confirmas que publicas exactamente el estado que has revisado. Si otra persona ha publicado entretanto, se rechaza la llamada con 409 conflict y tendrás que revisar de nuevo.

No se puede publicar una compilación mientras haya un bloqueo:

Reversión y anulación de publicación

Una reversión vuelve a servir la compilación de una publicación anterior, sin volver a compilar. El borrador no cambia, así que puede ser más reciente que lo que ven los visitantes. Un sitio conserva sus últimas 50 publicaciones para poder revertirlas.

Anular la publicación deja el sitio fuera de línea: los visitantes ven que no hay ningún sitio en esa dirección hasta que vuelvas a publicar. No se elimina nada.

Para publicar, revertir o anular la publicación se necesita el ámbito sites:publish, y solo puede hacerlo un administrador del espacio de trabajo. Un agente sin ese ámbito puede prepararlo todo y pedir al propietario que publique.

Exportación e importación

El proyecto completo se exporta como un archivo tar que se puede compilar en cualquier lugar con npm ci && npm run build. Al importar un archivo, se sustituyen los archivos del borrador por los que contiene, en una sola revisión. Se omiten node_modules, dist, .git y los archivos secretos. La importación no compila ni publica.