Crear páginas en Astro es tan simple como añadir archivos dentro de una carpeta. Aquí aprenderás a generar rutas usando archivos .astro y Markdown, montar una página de error 404 funcional y preparar contenido enriquecido sin escribir HTML. Es una guía pensada para quienes empiezan con Astro y quieren entender el ruteo basado en archivos.

¿Cómo funciona el sistema de rutas basado en archivos en Astro?

Astro utiliza la carpeta pages como punto central para definir las rutas de tu proyecto. Cada archivo que crees dentro se convierte automáticamente en una página accesible desde el navegador, sin necesidad de configurar un router aparte.

Las extensiones soportadas son varias y cada una tiene su propósito:

• .astro para componentes con lógica y estructura completa.
• .md para contenido en Markdown enfocado en texto.
• .mdx para Markdown extendido con componentes (requiere integración).
• .html para páginas estáticas tradicionales.
• .js, .ts y .tsx para rutas dinámicas o endpoints.

¿Qué es el ruteo basado en archivos en Astro? Es un sistema donde cada archivo dentro de pages se convierte en una ruta. Si creas about.md, automáticamente existirá /about en tu sitio.

¿Cómo armar una página de error 404 en Astro?

La página 404 aparece cuando alguien escribe una URL que no coincide con ningún archivo dentro de pages. Astro la detecta de forma automática siempre que el archivo se llame 404.astro.

Pasos para construir el 404 con HyperUI y Tailwind

Para este ejemplo se usa HyperUI, una librería de componentes escritos en Tailwind CSS que ofrece secciones listas para copiar.

1. Crea el archivo 404.astro dentro de pages.
2. Entra a HyperUI y navega a la categoría Application UI, sección de errores.
3. Copia el HTML del template que prefieras y pégalo en tu archivo.
4. Cambia el href="#" del botón de regreso por href="/" para que apunte al home.
5. Guarda y prueba escribiendo cualquier URL inexistente, por ejemplo asdasd.

Como este componente solo muestra contenido estático, no hace falta agregar el bloque de script en la parte superior del archivo ni la etiqueta style. Tailwind se encarga de los estilos vía clases.

¿Cuándo se muestra la página 404 en Astro? Cuando la URL solicitada no coincide con ningún archivo dentro de la carpeta pages. Astro la dispara automáticamente si existe 404.astro.

¿Cómo crear una página en Markdown dentro de Astro?

Markdown te permite escribir contenido sin pelearte con etiquetas HTML. Es ideal para páginas tipo about, blogs o documentación, donde el foco está en el texto y no en la estructura visual.

Estructura básica de un archivo .md en Astro

Dentro de pages crea el archivo about.md. Al inicio del documento se usa una lista de propiedades llamada frontmatter, delimitada por tres guiones, donde puedes declarar variables que luego serán accesibles desde componentes y plantillas.

Ejemplo del contenido que se trabaja en la clase:

markdown

title: My first page

Hello, world!

Hello page with Astro

Con esto ya tienes una ruta /about funcional. Solo necesitas reemplazar la URL inexistente en la barra de direcciones por about y verás el contenido renderizado.

El detalle a considerar: el archivo Markdown se renderiza sin estilos propios ni layout. Astro toma el contenido y lo inserta tal cual en la estructura base de la página, así que verás el texto plano con la tipografía por defecto del navegador.

¿Por qué usar Markdown si no trae estilos?

Porque separa el contenido del diseño. Markdown te da agilidad para escribir y, en la siguiente etapa, podrás conectar estos archivos a una plantilla (layout) que aplique estilos consistentes a todas las páginas escritas en este formato.

¿Qué es el frontmatter en Markdown? Es un bloque al inicio del archivo, entre tres guiones, donde defines metadatos como título, fecha o autor. Astro lo expone como variables para usar en layouts.

Conceptos y herramientas que aparecen en la clase

A lo largo del recorrido se mencionan varios elementos que vale la pena tener claros para avanzar con confianza.

• Carpeta pages [0:05]: directorio raíz donde Astro busca los archivos que se convertirán en rutas del sitio.
• Archivo 404.astro [0:20]: página especial que se muestra cuando una ruta no existe dentro del proyecto.
• HyperUI [0:38]: librería de componentes en Tailwind CSS dividida en secciones como Marketing, E-commerce y Application UI, útil para acelerar la maquetación.
• Extensiones soportadas en pages [2:30]: .astro, .md, .mdx, .html, .js, .ts y .tsx, cada una con su caso de uso.
• Markdown [2:50]: formato ligero para escribir contenido enriquecido usando shortcuts en lugar de etiquetas HTML.
• Frontmatter [3:15]: lista de variables al inicio de un archivo .md, accesibles luego desde componentes y plantillas en Astro.

En la próxima clase llega lo interesante: las plantillas o layouts que envolverán estos archivos Markdown para darles diseño y coherencia visual. ¿Ya tienes en mente qué páginas vas a crear primero en tu proyecto? Cuéntame en los comentarios.