Crea un blog con Astro desde cero: guía completa de la home al despliegue en 1 hora

Un blog técnico carga completo en 0,8 segundos y la navegación es fluida. Tu WordPress tarda 3 segundos en pantalla en blanco y dan ganas de cerrar la pestaña. Antes probé Hexo, Hugo e incluso Gatsby, pero siempre me atascaba en algo: documentación confusa, tutoriales fragmentados, sensación de que faltaba algo entre la instalación y el despliegue. Astro va muy rápido, la experiencia de desarrollo es buena y todo el flujo es más simple de lo que pensaba.

Este artículo te guía de cero al despliegue: en 1 hora tendrás un blog con home, listado, etiquetas y RSS. Pasos concretos, sin relleno.

Capítulo 1: ¿Por qué Astro? (No es publicidad, de verdad funciona)

¿La diferencia de rendimiento es tan grande?

Sinceramente, al principio también lo dudaba. La web dice «un 40 % más rápido que React» y «cero JavaScript por defecto»; suena a marketing, ¿no? Pero tras migrar mi blog de WordPress a Astro, los datos no mienten:

• Tiempo de carga inicial: de 3,2 s a 0,8 s
• Lighthouse: 100 puntos (WordPress solo 65)
• Volumen de JavaScript: de 280 KB a menos de 20 KB

¿Cómo se consigue? La clave está en la idea de Astro: contenido primero, JavaScript bajo demanda. Por defecto genera HTML+CSS puro; solo carga JS donde necesitas interactividad. Muy distinto al enfoque «todo el paquete» de React.

Un dato curioso: el mismo artículo en Next.js y en Astro. Next.js carga el runtime del framework (~100 KB) en la primera pantalla; Astro es un HTML limpio. En un blog orientado a lectura, la diferencia se nota mucho.

¿Cómo es la experiencia de desarrollo?

Tras el rendimiento, la experiencia. Lo que más me gusta es la arquitectura Islands: suena técnico, pero es «JavaScript solo donde hace falta».

En una página de artículo:

• Cuerpo del artículo → HTML estático (rápido)
• Comentarios → componente React (interactivo)
• Barra de navegación → componente Vue (sí, puedes mezclar)

No conviertes todo el sitio en SPA por una función pequeña. Y para principiantes: escribes en Markdown, sin base de datos ni panel. Yo escribo en VSCode, push a GitHub y despliegue automático.

¿Y frente a otros frameworks?

Seguro te lo preguntas; yo también. Comparemos con datos:

Mi consejo:

• Blog o documentación técnica: Astro primero; rendimiento y DX al día
• E-commerce o mucha interactividad: Next.js
• Blog estático mínimo, sin personalización: Hexo basta
• Equipo no técnico publicando: WordPress

En 2025, las descargas npm de Astro superan los 3 millones y la cuota de mercado llega al 18 %. Cada vez más desarrolladores lo eligen; ya no es un nicho.

Capítulo 2: Preparar el entorno (5 minutos)

Instalar Node.js (si aún no lo tienes)

Astro requiere Node.js v18 o superior. Comprueba tu versión:

node -v
npm -v

Si ves números, salta este paso. Si no, descarga la LTS en Node.js.

Detalle en Windows: marca «Add to PATH» al instalar. Algunos antivirus bloquean npm; tras instalar, reinicia la terminal.

Crear el proyecto Astro

Más simple de lo que crees. En la terminal:

npm create astro@latest

Te harán varias preguntas; así las respondo yo:

1. Nombre del proyecto: el que quieras, p. ej. my-blog
2. Plantilla: Blog (flechas + Enter)
3. Instalar dependencias: Yes
4. TypeScript: Strict o Strictest (el tipado evita bugs)
5. Inicializar Git: Yes

Tarda 1-2 minutos en descargar plantilla y dependencias.

¿Por qué la plantilla Blog? Ya trae listado, etiquetas y RSS; desde cero solo la paginación me costó dos horas la primera vez.

Arrancar el servidor de desarrollo

Entra al proyecto y arranca:

cd my-blog
npm run dev

Cuando veas Local: http://localhost:4321, abre esa URL: ya tienes un esqueleto de blog.

Trampas habituales:

• Puerto 4321 ocupado: cambia server.port en astro.config.mjs
• Error EACCES: prueba sudo npm run dev (Mac/Linux)
• Caracteres raros: comprueba UTF-8 en la terminal

Ya tienes un blog Astro funcionando. Veamos qué hace cada carpeta.

Capítulo 3: Estructura del proyecto (para qué sirve cada carpeta)

¿Cómo se ve el directorio?

Abre my-blog en VSCode u otro editor:

my-blog/
├── src/
│   ├── pages/           # Rutas: el nombre del archivo es la URL
│   ├── layouts/         # Layouts (cabecera, pie, etc.)
│   ├── components/      # Componentes reutilizables
│   └── content/         # Artículos Markdown
├── public/              # Estáticos (imágenes, fuentes, favicon)
├── astro.config.mjs     # Configuración de Astro
└── package.json         # Dependencias

Parece un proyecto frontend normal, pero Astro tiene detalles que explican por qué encaja tan bien en blogs.

pages/: archivo = ruta

Lo que más me gusta: no configuras rutas; el nombre del archivo es la URL:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

• pages/index.astro → home /
• pages/about.astro → /about
• pages/blog/index.astro → listado /blog
• pages/blog/[...slug].astro → detalle /blog/xxx

[...slug].astro es ruta dinámica; lo entre corchetes es variable. Atiende todos los enlaces bajo /blog/.

Mucho más simple que el enrutado de Next.js; al migrar, me encantó.

content/: dónde viven los artículos

En src/content/blog/ hay artículos de ejemplo. Cada uno es .md o .mdx con frontmatter (entre tres guiones):

---

title: 'Mi primer artículo'
description: 'Artículo de prueba'
pubDate: 'Dec 02 2025'
heroImage: '/blog-placeholder.jpg'
tags: ['Astro', 'tutorial']

---

Aquí empieza el cuerpo...

Astro lee esos campos; en la página usas post.data.title. Hay validación de tipos: un campo mal escrito falla en build, ideal si eres perfeccionista.

layouts/ y components/: reutilizar código

layouts/ para estructura común (cabecera, pie, sidebar). La plantilla Blog trae BaseLayout.astro y BlogPost.astro.

components/ para piezas reutilizables: botones, tarjetas, nube de etiquetas. Pueden ser Astro, React o Vue.

public/: copiado tal cual al build

Lo de aquí va a la raíz del sitio. public/favicon.ico → https://tudominio.com/favicon.ico.

Suelo poner imágenes del blog, fuentes y robots.txt.

astro.config.mjs: configuración central

Controla el comportamiento de Astro:

export default defineConfig({
  site: 'https://tudominio.com',  // Dominio de despliegue
  integrations: [mdx()],          // Plugins (Markdown, RSS, etc.)
  server: {
    port: 4321                    // Puerto de desarrollo
  }
})

De momento no hace falta tocar mucho; volverás cuando añadas funciones.

Entender esta estructura ahorra tiempo. Mucha gente codea sin saber dónde va cada cosa y el proyecto acaba hecho un lío. Cinco minutos aquí valen una hora después.

Capítulo 4: Funciones clave (lo importante)

4.1 Home: artículos recientes

La plantilla Blog ya trae una home; la ajustamos. Abre src/pages/index.astro:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../layouts/BaseLayout.astro';

// Todos los posts, ordenados por fecha, últimos 5
const allPosts = (await getCollection('blog'))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
  .slice(0, 5);

---

<BaseLayout>
  <h1>Bienvenido a mi blog</h1>
  <ul>
    {allPosts.map((post) => (
      <li>
        <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
        <time>{post.data.pubDate.toDateString()}</time>
      </li>
    ))}
  </ul>
</BaseLayout>

¿Qué hace?

1. getCollection('blog') obtiene los artículos
2. Orden descendente por fecha
3. slice(0, 5) solo los cinco últimos
4. Renderiza la lista

Trampa: en el orden de fechas usa .valueOf(); si no, ordena como strings y se desordena.

4.2 Listado con paginación

Crea src/pages/blog/index.astro si no existe:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

const allPosts = (await getCollection('blog'))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const pageSize = 10;
const currentPage = 1;
const totalPages = Math.ceil(allPosts.length / pageSize);
const posts = allPosts.slice(0, pageSize);

---

<BaseLayout title="Listado de artículos">
  <h1>Todos los artículos</h1>

  <div class="post-list">
    {posts.map((post) => (
      <article>
        <h2><a href={`/blog/${post.slug}/`}>{post.data.title}</a></h2>
        <p>{post.data.description}</p>
        <time>{post.data.pubDate.toLocaleDateString('zh-CN')}</time>
        <div class="tags">
          {post.data.tags?.map(tag => <span>#{tag}</span>)}
        </div>
      </article>
    ))}
  </div>

  {totalPages > 1 && (
    <div class="pagination">
      <span>Página {currentPage} / {totalPages}</span>
    </div>
  )}
</BaseLayout>

Aquí simplifiqué la paginación; en producción puedes usar paginate() de Astro. Con menos de 100 artículos, una sola página suele bastar.

Mejoras UX:

• Tiempo de lectura estimado (palabras ÷ 400 palabras/min)
• Resumen truncado (150 caracteres + …)
• Miniatura con heroImage

4.3 Detalle del artículo: la página central

Ruta dinámica. Si la plantilla tiene src/pages/blog/[...slug].astro, edítala; si no, créala:

---

import { getCollection } from 'astro:content';
import BlogPost from '../../layouts/BlogPost.astro';

// Genera rutas estáticas para cada artículo
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();

---

<BlogPost {...post.data}>
  <Content />
</BlogPost>

La magia:

• getStaticPaths() corre en build y genera HTML por artículo
• post.render() convierte Markdown en componente
• <Content /> es el cuerpo del artículo

Donde suelen atascarse:

1. Sin resaltado de código: instala Shiki (la plantilla Blog suele traerlo)
2. Markdown feo: @tailwindcss/typography
3. Rutas de imagen: imágenes en public/, referencia /images/xxx.jpg

Para un índice (TOC), plugin remark-toc en astro.config.mjs:

import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkToc],
  },
});

4.4 Etiquetas: ordenar el contenido

Crea src/pages/tags/[tag].astro:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

export async function getStaticPaths() {
  const allPosts = await getCollection('blog');

  // Todas las etiquetas únicas
  const allTags = [...new Set(allPosts.flatMap(post => post.data.tags || []))];

  // Una página por etiqueta
  return allTags.map(tag => ({
    params: { tag },
    props: {
      posts: allPosts.filter(post =>
        post.data.tags?.includes(tag)
      ).sort((a, b) =>
        b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
      ),
    },
  }));
}

const { tag } = Astro.params;
const { posts } = Astro.props;

---

<BaseLayout title={`Etiqueta: ${tag}`}>
  <h1>#{tag} ({posts.length} artículos)</h1>

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</BaseLayout>

Cada etiqueta tiene su URL, p. ej. /tags/astro, /tags/tutorial.

Extra: página índice de etiquetas (src/pages/tags/index.astro) con nube y tamaño según número de artículos.

4.5 RSS: avisar de nuevos posts

Instala el plugin:

npx astro add rss

Crea src/pages/rss.xml.js:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');

  return rss({
    title: 'Mi blog técnico',
    description: 'Experiencias y aprendizajes de desarrollo frontend',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Tras desplegar, el feed está en https://tudominio.com/rss.xml. Pocos usan RSS hoy, pero en un blog técnico queda profesional.

Ya tienes home, listado, detalle, etiquetas y RSS. Siguiente paso: que te encuentren en buscadores.

Capítulo 5: SEO (que encuentren tu blog)

Montar el blog no basta; hay que ser visible. Astro ayuda: HTML estático, carga rápida, etiquetas semánticas — lo que gusta a Google.

Meta tags: qué es tu página

En src/layouts/BaseLayout.astro, dentro de <head>:

---

interface Props {
  title: string;
  description?: string;
  image?: string;
}

const { title, description = 'Mi blog técnico', image = '/og-image.jpg' } = Astro.props;
const canonicalURL = new URL(Astro.url.pathname, Astro.site);

---

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width" />
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />

  <title>{title} | Mi blog</title>
  <meta name="description" content={description} />
  <link rel="canonical" href={canonicalURL} />

  <!-- Open Graph (redes sociales) -->
  <meta property="og:title" content={title} />
  <meta property="og:description" content={description} />
  <meta property="og:image" content={new URL(image, Astro.site)} />
  <meta property="og:url" content={canonicalURL} />

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content={title} />
  <meta name="twitter:description" content={description} />
  <meta name="twitter:image" content={new URL(image, Astro.site)} />
</head>

Cada página tendrá meta completa; al compartir en Twitter o WhatsApp se verá una tarjeta decente.

Sitemap: qué páginas indexar

Un comando:

npx astro add sitemap

En astro.config.mjs, tu dominio:

export default defineConfig({
  site: 'https://tudominio.com',
  integrations: [sitemap()],
});

Tras desplegar: https://tudominio.com/sitemap-index.xml. Envíalo a Google Search Console; en unos días pueden indexarse tus artículos.

Rendimiento: la velocidad también es SEO

Astro ya va rápido; aun así:

1. Optimizar imágenes

Usa <Image> en lugar de <img alt="">:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

---

import { Image } from 'astro:assets';
import myImage from '../assets/photo.jpg';

---

<Image src={myImage} alt="Texto descriptivo" />

Automáticamente:

• Formatos modernos (WebP/AVIF)
• Varias resoluciones responsive
• Lazy loading

2. Comprimir CSS/JS

En producción Astro comprime solo. Quita dependencias que no uses.

3. Fuentes

Con Google Fonts o propias, añade font-display: swap:

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/myfont.woff2') format('woff2');
  font-display: swap;
}

Con esto, Lighthouse suele quedarse en 95+. Mi blog solo pierde algo en Best Practices por scripts de terceros; el resto al máximo.

Capítulo 6: Despliegue (dos plataformas gratis)

El código está listo; toca publicarlo. Dos opciones gratuitas y sencillas; elige una.

Opción 1: Vercel (recomendada para empezar)

Soporte nativo de Astro, casi sin configuración.

Paso 1: subir a GitHub

Si aún no tienes repo, en la raíz del proyecto:

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/tu-usuario/my-blog.git
git push -u origin main

Paso 2: importar en Vercel

1. Regístrate en vercel.com (con GitHub es lo más fácil)
2. «New Project»
3. Elige el repo my-blog
4. Vercel detecta Astro; no cambies nada
5. «Deploy» y espera 1-2 minutos

Paso 3: visitar el blog

Tendrás un dominio xxx.vercel.app listo.

Dominio propio (opcional)

En ajustes del proyecto añade tu dominio y en el registrador un CNAME a la URL que te indique Vercel.

Trampas:

• site correcto en astro.config.mjs
• Variables de entorno en el panel de Vercel, no en el código
• El primer despliegue puede tardar 5 minutos

Opción 2: Netlify (alternativa)

Similar a Vercel; a veces mejor acceso desde ciertas regiones.

Paso 1: GitHub (igual que arriba)

Paso 2: importar en Netlify

1. netlify.com
2. «Add new site» → «Import an existing project»
3. Conecta GitHub y el repo
4. Build:
   • Build command: npm run build
   • Publish directory: dist
5. «Deploy»

Paso 3: probar en xxx.netlify.app

¿Cuál elegir?

Prueba Vercel; si va lento en tu zona, Netlify. Ambos despliegan al hacer push.

La magia del despliegue automático

A partir de ahora:

1. Escribes el artículo en Markdown
2. git add . → git commit -m "Nuevo artículo" → git push
3. En ~2 minutos está publicado

Sin SSH, sin build manual, sin subir archivos a mano. La primera vez impresiona.

Capítulo 7: Problemas frecuentes (trampas que ya pisé)

Errores reales míos y de la comunidad; conocerlos ahorra tiempo.

Problema 1: Tailwind no aplica estilos

Síntoma: clases Tailwind sin efecto.

Causa: en tailwind.config.mjs, content no incluye tus archivos.

Solución:

export default {
  content: [
    './src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Reinicia el dev server (Ctrl+C, luego npm run dev).

Problema 2: build falla con «Invalid frontmatter»

Síntoma: en local bien, npm run build falla.

Causa: frontmatter mal formado o campos obligatorios faltantes.

Solución:

Revisa src/content/config.ts. La plantilla Blog suele exigir:

---

title: 'Título'           # Obligatorio
description: 'Descripción'     # Obligatorio
pubDate: 'Dec 02 2025'     # Obligatorio, formato de fecha
tags: ['tag1', 'tag2']   # Opcional

---

Content Collections valida en build y evita sorpresas en producción.

Problema 3: 404 en producción, bien en local

Síntoma: artículos 404 en Vercel/Netlify.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Causa: base o site mal en astro.config.mjs.

Solución:

export default defineConfig({
  site: 'https://tudominio.com',  // Obligatorio
  // base: '/blog',  // Solo si despliegas en subdirectorio
});

Si el blog está en la raíz del dominio, no uses base.

Problema 4: imágenes lentas

Síntoma: imágenes tardan en cargar.

Causa: sin componente Image o archivos demasiado grandes.

Solución:

1. Componente Image:

---

import { Image } from 'astro:assets';

---

<Image src="/images/photo.jpg" alt="Descripción" width={800} height={600} />

2. Comprimir: TinyPNG o Squoosh.app antes de subir

3. CDN: Cloudinary, Imgur, etc.

Problema 5: código sin resaltado

Síntoma: bloques de código en texto plano.

Causa: tema no configurado o Shiki roto.

Solución:

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'github-dark',  // o 'dracula', 'nord', etc.
    },
  },
});

La plantilla Blog suele traer Shiki; si no, rm -rf node_modules && npm install.

Problema 6: dev server lento al arrancar

Síntoma: npm run dev tarda mucho.

Causa: muchos artículos o demasiados plugins.

Solución:

• Borra node_modules y package-lock.json, reinstala
• Quita plugins innecesarios
• Actualiza Astro: npm install astro@latest

Astro 5 mejoró mucho el arranque; si sigues en 4.x, conviene subir.

Probablemente no te pase todo esto; si pasa, vuelve a este capítulo.

Conclusión

Si llegaste hasta aquí, enhorabuena: tienes un blog Astro completo, rápido y usable. Resumen de lo logrado:

✅ Sistema completo: home, listado, detalle, etiquetas, RSS
✅ SEO: meta, sitemap, rendimiento
✅ Despliegue moderno: CI/CD con push
✅ Rendimiento: Lighthouse 95+, ~0,8 s de carga inicial

Además entiendes la idea de Astro: contenido primero, rendimiento arriba. Sirve para blogs y otros sitios estáticos.

¿Qué sigue?

Hazlo ya (no lo pospongas):

• Practica 1 hora con esta guía al lado
• Publica tu primer artículo real, aunque sea de prueba
• Comparte y pide feedback

Funciones extra (con calma):

• Comentarios: Giscus o Disqus
• Búsqueda: Algolia DocSearch o Pagefind
• Modo oscuro: botón de tema
• Analytics: Google Analytics o Plausible
• Anterior / siguiente entre artículos

Recursos (profundizar):

• Documentación oficial de Astro — referencia; hay versión en chino
• Astro 中文网 — comunidad en chino
• Astro Paper — plantilla con buen SEO
• Discusiones en GitHub de Astro

Comunidad:

• Astro Discord
• Busca «awesome-astro» en GitHub
• Comparte tu blog en el canal Showcase de Discord

Una última cosa

Montar el blog es solo el primer paso; lo difícil es escribir con constancia. He visto blogs perfectos abandonados tras dos posts, y WordPress simples con cientos de miles de visitas al mes tras años publicando. Astro baja la barrera técnica; el resto depende de ti.

Si te atasacas:

1. Troubleshooting en la documentación oficial
2. Issues en GitHub con tu error
3. Pregunta en Astro Discord (hay canal en chino)

No tengas miedo a equivocarte; a mí me costó tres días el primer blog Astro. Después, mantenerlo es mucho más fácil.

Abre la terminal y empieza tu blog con Astro. 💫