Crear tu primera página en Astro es más sencillo de lo que parece cuando entiendes la estructura de archivos del framework. Aquí aprenderás a generar una nueva ruta, escribir HTML, aplicar estilos con alcance local y visualizar el resultado en tu entorno de desarrollo, ideal si estás construyendo tu portafolio web.

¿Cómo está organizada la estructura de archivos en un proyecto Astro?

Antes de tocar código, conviene entender qué hace cada carpeta dentro del proyecto. Astro propone una organización clara que separa páginas, layouts y componentes para que cada pieza tenga una responsabilidad concreta.

El punto de entrada vive en la carpeta pages, dentro del archivo index.astro. Al abrirlo notarás que los archivos .astro tienen una estructura particular dividida en tres zonas [00:32]:

• La parte superior, donde escribes la lógica de JavaScript del archivo.
• El centro, donde colocas el template HTML con la marcación de la página.
• La parte inferior, reservada para los estilos.

Esta propuesta te permite tener todo lo necesario de una sección en un mismo archivo, sin saltar entre carpetas para encontrar el CSS o el script asociado.

¿Qué diferencia hay entre pages, layouts y components?

Dentro de pages encontrarás archivos como 404, about y la sección work, cada uno representando una ruta distinta del sitio. Aunque son páginas diferentes, suelen compartir una base común de layout [01:15].

Esa base vive en la carpeta layouts, donde un archivo como BaseLayout define la estructura repetida: cabecera, cierre del documento, estilos globales y scripts. Los componentes, en cambio, son piezas más pequeñas e individuales que conforman cada página y muchas veces solo necesitan HTML y estilos, sin JavaScript.

¿Qué es un layout en Astro? Es una plantilla reutilizable que envuelve el contenido de varias páginas. Te ahorra repetir el mismo head, header o footer en cada archivo nuevo.

En work también verás rutas dinámicas con la sintaxis del slug entre corchetes, que sirven para renderizar contenido variable según la URL. Más adelante profundizarás en cómo se llama esa información para hacer render dentro del enrutamiento dinámico.

¿Cómo crear una nueva página en Astro desde cero?

Vamos a lo práctico. Para crear una página nueva, ubícate en la raíz de la carpeta pages y crea un archivo llamado blog.astro. Con eso ya tienes una ruta lista en /blog.

Dentro del archivo respeta la estructura del framework. La parte superior queda reservada para JavaScript, aunque en este caso no la usaremos. Luego escribe el HTML con un div que contenga un h2 con el texto ¡Hola, blog!.

Para darle estilo, usa la etiqueta style en la parte inferior del archivo. Aquí puedes definir, por ejemplo, un font-size grande para ese h2 específico.

astro

---

<div> <h2>¡Hola, blog!</h2> </div> <style> h2 { font-size: 3rem; } </style>

¿Por qué los estilos de Astro no afectan a otras páginas?

Esta es una de las ventajas más potentes del framework. Los estilos declarados dentro de un archivo .astro solo aplican a ese archivo [04:10]. No tienes que preocuparte de que tu h2 del blog rompa el h2 del hero o del about.

Astro logra esto generando un hash único por cada clase declarada dentro del alcance de la página. Si inspeccionas el HTML renderizado verás clases con identificadores extraños añadidos automáticamente.

¿Qué es el scoped CSS en Astro? Es un sistema que aísla los estilos de cada archivo .astro agregando un identificador único a las clases, evitando conflictos entre páginas o componentes.

Gracias a esto puedes enfocarte en construir cada sección con tranquilidad, sabiendo que tus reglas no van a chocar con otras partes del sitio.

¿Cómo levantar y visualizar el proyecto en el navegador?

Para ver tu nueva página funcionando necesitas el entorno de desarrollo local activo. Si lo tenías corriendo, Astro detecta los cambios automáticamente y te muestra en la terminal cuál archivo se actualizó, por ejemplo src/pages/blog.astro con sus líneas de código.

Si paraste el proceso con Ctrl+C, vuelve a iniciarlo con:

bash npm run dev

Una vez levantado, abre el navegador en localhost:3000 o el puerto que estés usando, y agrega /blog a la URL. Ahí verás tu título renderizado con los estilos que definiste.

¿Cuándo necesitas reiniciar el servidor de Astro?

No siempre tienes que matar el proceso. Astro hace hot reload cuando modificas páginas, componentes o estilos. Sin embargo, hay archivos donde el reinicio es obligatorio [06:45]:

• astro.config cuando cambias la configuración base del framework.
• Configuraciones de Tailwind si modificas presets o plugins.
• Archivos de TypeScript que afecten la compilación.

En esos casos detén el servidor con Ctrl+C y vuelve a ejecutar npm run dev para que los cambios se apliquen.

Con esto ya tienes tu primera página en Astro y entiendes cómo se relacionan páginas, layouts y componentes dentro del proyecto. Ahora explora el resto de la estructura del portafolio, toma nota de lo que no te quede claro y cuéntanos en los comentarios qué sección quieres construir primero.