Publicar Astro desde Git: Markdown y rutas estáticas

Un cuaderno, un blog pequeño o una web de documentación pueden convertirse en archivos HTML antes de recibir visitas. Astro permite construir ese contenido desde Markdown y componentes: el resultado estático se publica sin mantener abierto el servidor de desarrollo.

Esta guía usa Cuaderno orbital, un ejemplo original con licencia MIT. Puedes abrir la portada publicada y la nota Markdown. Tiene CSS e ilustración propios; no incluye cuentas, pagos, API ni base de datos.

Si tu web tiene traducciones, comprueba las rutas y el cambio de idioma en Astro. El diagnóstico utiliza un ejemplo local con páginas equivalentes; no demuestra una entrega multilingüe nativa en Hostbrid.

Comprueba que tu proyecto es estático

Revisa astro.config.mjs y los scripts de package.json. El ejemplo declara output: 'static', no lleva adaptador de servidor y su script build ejecuta astro build. Genera los archivos que necesita cada ruta.

Astro también puede renderizar páginas bajo demanda. Una aplicación con SSR, sesiones, actions o endpoints vivos requiere un adaptador y un runtime compatible. Esta receta sólo comprueba la salida estática. No elimines funciones de backend para hacer que una aplicación parezca compatible; consulta qué alojamiento necesita una web creada con IA y la referencia oficial de output.

Escribe una nota en Markdown

El ejemplo guarda su nota en src/pages/notas/primera-noche.md. Su frontmatter contiene título, descripción y el layout que comparte con la portada. El contenido se transforma en HTML durante la construcción; la portada descubre las notas mediante import.meta.glob y muestra sus títulos y enlaces.

Para empezar, edita la nota existente y conserva sus campos de título, descripción y layout. Añadir otro archivo .md en esa carpeta genera otra página y permite que el listado lo descubra en el siguiente build. Revisa también el texto editorial del listado si amplías el cuaderno. La documentación de Markdown de Astro explica la diferencia entre estas páginas y colecciones de contenido con esquema.

Cambiar un archivo en tu ordenador no cambia lo publicado: conserva la modificación en Git y realiza una nueva construcción mediante el flujo de tu proyecto.

Construye con versiones reproducibles

Haz un fork o copia el repositorio conservando la licencia. Incluye package.json, package-lock.json, astro.config.mjs, src y public; no incluyas node_modules ni claves privadas.

El ejemplo fija Astro 7.3.7. La instalación oficial requiere Node 22.12.0 o superior y no admite versiones impares. Lo comprobamos localmente con Node 22.23.3, indicado en .nvmrc. El preset de Hostbrid se llama node22; ese nombre no identifica una versión patch exacta.

npm ci
npm run build

Busca dist/index.html, dist/notas/primera-noche/index.html y dist/orbital.svg. En este build pequeño, Astro incluye el CSS en los HTML: no necesitas encontrar una carpeta de CSS separada para saber que se ha aplicado. npm run dev y npm run preview son herramientas locales.

Configura la URL pública antes del build

En este ejemplo, PUBLIC_SITE_URL es una variable que lee su configuración para establecer site. Contiene la URL pública, nunca una contraseña. La publicación comprobada utilizó:

PUBLIC_SITE_URL=https://hostbrid-astro-demo.hostbrid.dev npm run build

Para tu copia, usa tu propia URL final, sin reutilizar el dominio de la demo. En Projects, configura esa variable antes de construir. Si no se define, el ejemplo utiliza https://example.invalid y añade noindex: es una guarda para las pruebas locales, no una configuración para publicar una web indexable. Revisa canonical y robots después de cada cambio.

La variable no configura DNS y no es una opción que todos los repositorios Astro lean automáticamente. Este ejemplo está diseñado para la raíz de un dominio; publicarlo bajo una subcarpeta exige adaptar base, enlaces y assets, y volver a comprobarlos.

Selecciona el preset de Astro en Projects

Sigue la documentación de Projects para conectar Git y revisar sus permisos. El repositorio independiente del ejemplo utilizó estos ajustes:

Un monorepo necesita la subcarpeta donde están package.json y la configuración. Publica el resultado de dist, no el código fuente. El contrato de construcción y salida coincide con la guía oficial de despliegue.

Prueba las rutas reales después de publicar

Escribe /notas/primera-noche/ directamente en el navegador y recarga. Astro ya ha generado su HTML: este ejemplo no necesita el marcador .hostbrid-spa ni un fallback a la portada. Una ruta que no se ha generado debe devolver 404; un asset inexistente también.

Verificado el 8 de octubre de 2026: el commit e3bdd60 se construyó y publicó mediante Projects. Portada, nota e imagen devolvieron 200, con hashes iguales al artefacto y en ambas réplicas. Chrome comprobó las dos rutas a 390 y 1280 px, CSS, imagen, enlaces y navegación, sin overflow ni POST. Canonical usa el dominio real; no había meta noindex ni cabecera X-Robots-Tag en esas respuestas. Rutas y assets ausentes devolvieron 404. Esto no demuestra indexación por un buscador.

La prueba se hizo con un proyecto propio y un build manual: no valida el alta de un cliente, OAuth de su cuenta ni publicación automática al recibir un push. Tampoco demuestra soporte de Astro SSR o de servicios externos. Consulta Projects y los planes vigentes para elegir capacidad según tu cuenta y tu aplicación.