Desarrollo, parte 1 de 1
¡Hemos migrado! Frikiteam, ahora un blog estático con Astro
¡Hemos migrado!
Desde el 22 de noviembre de 2026, frikiteam.es ya no es WordPress: es el sitio que describe esta página. Para ti casi nada cambia: las direcciones de siempre siguen funcionando (las 76 antiguas, con sus redirecciones), el RSS sigue en /feed/, y las entradas cargan en unos 170 KB. Lo nuevo: un buscador en la cabecera (pulsa / o Ctrl/⌘+K), series dibujadas como líneas de metro, y las erratas y las dudas se mandan por GitHub. El sitio no usa cookies.
El problema
WordPress hacía todo en el servidor: PHP, MySQL, Redis, un proxy con TLS y un script que vigilaba que nada de eso se rompiera. Cuatro contenedores para servir lo que, en el fondo, son 150 textos que cambian una vez al día. Cada actualización de núcleo o de plugin había que vigilarla, y cada visita ejecutaba código para generar una página idéntica a la anterior.
Un sitio estático da la vuelta a eso: el trabajo se hace una vez, al compilar, y lo que se sirve son ficheros. Pero un blog con series, búsqueda y entradas programadas parece pedir un servidor. Esta página cuenta cómo se resuelve cada una de esas tres cosas con Astro sin ninguno, con los números medidos y los problemas reales que salieron por el camino.
Qué cubre y qué no
Es la arquitectura de este blog, con las versiones de noviembre de 2026 (Astro 7, Pagefind 1.6, Wrangler 4.166, Node 26). No es un tutorial de Astro: para eso están sus guías. El paso previo, de Markdown en este repositorio a artículo del blog, lo hace scripts/publish_to_astro.py y está descrito en el CLAUDE.md del repo.
En cifras, a 22 de noviembre de 2026: 147 artículos en 11 series, 83 páginas HTML, un dist/ de 10 MB, un build completo de unos 4 segundos y ningún fichero JavaScript propio en el sitio compilado.
Visión general
El sitio es un proyecto de Astro que lee Markdown y produce HTML. Un Worker de Cloudflare lo sirve con static assets: sin código de servidor, solo el directorio dist/.

| Pieza | Para qué | Versión |
|---|---|---|
| Astro | Genera las páginas | 7.4 |
@astrojs/markdown-satteri |
Procesador de Markdown | 0.4 |
| Pagefind | Buscador sin servidor | 1.6 |
@astrojs/sitemap, @astrojs/rss |
Sitemap y RSS | 3.7 y 4.0 |
| Wrangler | Despliega dist/ en Cloudflare Workers |
4.166 |
El comando de build encadena tres pasos, y que falle cualquiera de ellos detiene el despliegue:
astro build && pagefind --site dist && node scripts/check-build.mjs
Desde el git push hasta ver el cambio en línea pasan unos 90 segundos (medido el 22/11/2026).
Las entradas son una colección con esquema
Cada artículo es un .md con frontmatter validado por un esquema de Zod. Si algo no encaja, el build falla en vez de publicar una página rota:
// src/content.config.ts
const posts = defineCollection({
loader: glob({ pattern: '*.md', base: './src/content/posts' }),
schema: z.object({
title: z.string(),
source: z.string().optional(), // página de Frikiteam-docs de la que sale
date: z.coerce.date(),
updated: z.coerce.date(),
category: z.enum(slugs), // exactamente una serie por entrada
description: z.string(),
tags: z.array(z.string()),
}),
});
Con una serie que no existe, el build termina con un error y código de salida 1:
[InvalidContentEntryDataError] posts → ceph data does not match collection schema.
category: Invalid option: expected one of "almacenamiento"|"automatizacion"|...
El reparto de responsabilidades entre los dos repositorios es lo que evita pisarse:
| Dato | Dónde vive | Quién lo cambia |
|---|---|---|
Cuerpo, título, extracto, etiquetas, updated |
Página de este repo | El generador, en cada ejecución |
Serie (category), fecha de salida, imagen |
El .md del artículo en Astro |
Tú; el generador nunca lo pisa |
URL (/serie/slug/) |
Sale de los dos anteriores | Congelada al publicar |
Cambiar la serie cambia la URL
La URL incluye la serie. Mover un artículo ya publicado a otra serie deja la dirección antigua en 404 si no añades una redirección.
Publicación programada en un sitio estático
Sin servidor no hay nadie que «publique a las 9:00». La solución son dos ideas: la fecha es un dato del artículo, y un único filtro decide qué existe.
// src/lib/site.ts
const BUILD_TIME = Date.now();
export async function allPosts() {
return (await getCollection('posts', (p) => p.data.date.getTime() <= BUILD_TIME))
.sort((a, b) => b.data.date.getTime() - a.data.date.getTime());
}
Todas las rutas, el RSS, el mapa de series y el sitemap leen de allPosts(), así que una entrada futura no puede colarse por ningún lado. Un artículo sale en la primera compilación posterior a su fecha.
Para no fiarlo todo a una convención, el último paso del build lo comprueba por fuera, leyendo los ficheros y no el código de Astro:
// scripts/check-build.mjs (resumen)
if (date > now && built) leaked.push(f); // programada, pero publicada
if (date <= now && !built) missing.push(f); // debida, pero sin página
if (leaked.length || missing.length) process.exit(1);
Falta lo que dispara la compilación cada día. Una Action de GitHub llama al deploy hook de Cloudflare, pero antes comprueba si hace falta:
on:
schedule:
- cron: '5 7 * * *' # 09:05 Madrid en verano
- cron: '5 8 * * *' # 09:05 Madrid en invierno
- cron: '35 9 * * *' # de recuperación
- cron: '5 12 * * *'
jobs:
deploy:
steps:
- uses: actions/checkout@v7
- id: live
run: node scripts/check-live.mjs "$LIVE" 0 && echo "done=true" >> "$GITHUB_OUTPUT" || true
- if: steps.live.outputs.done != 'true'
env: { HOOK: "${{ secrets.CF_DEPLOY_HOOK }}" }
run: curl -fsS -X POST "$HOOK" > /dev/null
- if: steps.live.outputs.done != 'true'
run: node scripts/check-live.mjs "$LIVE" 15
check-live.mjs busca la última entrada que ya toca y mira que esté en su URL y enlazada desde la portada. Con 0 solo sondea; con 15 espera hasta 15 minutos y, si no aparece, falla en rojo, que es el aviso por correo.
El cron de GitHub no es un reloj
La documentación de GitHub lo dice: el evento schedule puede retrasarse en picos de carga, el inicio de cada hora es uno de ellos, y con carga alta algunos trabajos en cola pueden descartarse. A nosotros nos pasó: el 22/11/2026 no se ejecutó ni el cron de las 07:05 ni el de las 08:05 UTC, y la entrada de las 09:00 dio 404 hasta lanzar la Action a mano. Los primeros disparos por cron llegaron a las 15:13, 16:11 y 19:29 UTC, que no coinciden con ninguna hora programada.
Por eso hay cuatro disparos y por eso cada uno es idempotente: si la entrada ya está en línea, no hacen nada. La propia documentación aconseja, además, programar a un minuto distinto del inicio de la hora.
Series como líneas de metro
Una serie es un recorrido ordenado, y la web lo dibuja como una línea de metro: una parada por entrada, en orden de lectura. El orden es el de la fecha dentro de la serie:
export async function seriesOf(cat: string) {
return (await allPosts()).filter((p) => p.data.category === cat).reverse();
}
El componente SeriesLine.astro pinta una lista ordenada con un punto por entrada. Tres detalles que conviene conocer:
- El tooltip con el título es un único elemento
position: fixedque se añade al<body>. Dentro de la línea no cabe: el contenedor tieneoverflow-x: autopara poder desplazarse y recortaría cualquier cosa que sobresalga. - El punto mide 14 px. El área de toque se amplía con un pseudo-elemento hasta 34×28 px, por encima de los 24 px que pide WCAG 2.5.8. Solo en horizontal, porque el contenedor recorta en vertical, y sin llegar a las paradas vecinas, que están a 35 px.
- Cada parada lleva el título como texto (oculto con una clase
sr-only). Solo conaria-label, los buscadores no ven texto de enlace.
Markdown con Sätteri y un plugin propio
Astro 7 renderiza el Markdown con Sätteri, su procesador nativo, en lugar de remark/rehype. Los plugins de remark ya no valen tal cual: la opción markdown.rehypePlugins exige instalar @astrojs/markdown-remark y usar el procesador unified(). Aquí se portó el plugin a Sätteri.
Las páginas de este repositorio enlazan entre sí con rutas relativas (../docker/quadlets.md#x), que en el blog no existen. Un plugin de HAST las resuelve al compilar: a la entrada correspondiente si ya está publicada y, si no, a la página en docs.frikiteam.es:
// astro.config.mjs
markdown: { processor: satteri({ hastPlugins: [docLinks] }) },
// src/lib/doc-links.mjs
export default ({ fileURL }) => {
const from = fileURL && sourceOf(readFileSync(fileURL, 'utf8')); // página de origen
return from && {
name: 'doc-links',
element: {
filter: ['a'],
visit(node, ctx) {
const to = resolveDocLink(from, node.properties.href);
if (to) ctx.setProperty(node, 'href', to);
},
},
};
};
Dos detalles que cuestan un rato:
setAttributeno sirve para un elemento HTML. Es para atributos de JSX/MDX; para una propiedad de<a>se usasetProperty.- Los
idde los encabezados. El Markdown de MkDocs genera ids sin tildes (#que-es), y los índices de las propias páginas enlazan con ellos. El generador de Astro conserva las tildes, así quescripts/publish_to_astro.pyemite cada encabezado con suidexplícito, el mismo que daba MkDocs.
Búsqueda con Pagefind
Pagefind indexa el HTML ya compilado. Se ejecuta tras astro build y solo mira lo marcado con data-pagefind-body, que aquí es el cuerpo de cada artículo: 63 páginas y 13.489 palabras. El índice ocupa 1,4 MB en dist/pagefind/, y el navegador solo descarga los fragmentos que necesita.
El buscador no se carga con la página. Un botón en la cabecera abre un <dialog> y es entonces cuando se pide Pagefind:
const load = () => (loading ??= new Promise((done, fail) => {
const css = document.createElement('link');
css.rel = 'stylesheet'; css.href = '/pagefind/pagefind-ui.css';
const js = document.createElement('script');
js.src = '/pagefind/pagefind-ui.js';
js.onload = () => { ui = new PagefindUI({ element: '#search', showImages: false }); done(); };
document.head.append(css, js);
}));
Atajos / y Ctrl/⌘+K para abrirlo, y /?q=palabra lo abre con la búsqueda hecha, que es la dirección a la que redirige la antigua /buscar/?q=. La serie es un filtro (data-pagefind-filter="serie") y el título va como metadato.
Texto oculto que se cuela en los extractos
El título y la serie viajaban en elementos ocultos dentro del cuerpo indexado, y aparecían pegados al principio del extracto («ContenedoresContenedores»). La solución es marcarlos con data-pagefind-ignore: según la documentación de Pagefind, así salen del índice de texto pero los filtros y los metadatos que contienen siguen funcionando.
Redirecciones, caché y cabeceras en Workers
Un Worker con static assets se configura con un wrangler.jsonc mínimo:
{
"name": "frikiteam-astro",
"compatibility_date": "2026-11-01",
"assets": { "directory": "./dist", "not_found_handling": "404-page" }
}
No borres `wrangler.jsonc`
Sin él, npx wrangler deploy intenta autoconfigurar el proyecto y le añade el adaptador @astrojs/cloudflare, que rompe un sitio puramente estático. Fue el primer fallo del despliegue.
Redirecciones. Cloudflare lee un fichero _redirects, pero Astro no enruta los ficheros que empiezan por _. Se genera como un endpoint con otro nombre (redirects.txt) y una integración lo renombra al terminar el build. Salen 163 reglas: las URL con fecha de WordPress, el mapa de entradas fusionadas, /<serie>/ → /category/<serie>/ y las del feed, el sitemap y la paginación antiguos. El límite es de 2.000 redirecciones estáticas y 100 dinámicas (las que llevan :slug o *); aquí hay 6 dinámicas.
Cada regla, con y sin barra final
/devsecops/ redirigía, pero /devsecops daba 404: Cloudflare solo aplica la regla a la ruta exacta, y solo añade la barra por su cuenta a los ficheros que existen. La solución es emitir las dos variantes de cada regla.
Caché y cabeceras. public/_headers admite hasta 100 reglas; aquí hay 8:
/_astro/*
Cache-Control: public, max-age=31536000, immutable
/diagrams/*
Cache-Control: public, max-age=2592000, stale-while-revalidate=86400
/*
Referrer-Policy: strict-origin-when-cross-origin
X-Frame-Options: SAMEORIGIN
Permissions-Policy: camera=(), microphone=(), geolocation=()
Los ficheros de /_astro/ llevan un hash en el nombre, así que nunca cambian bajo la misma URL y pueden ser inmutables. Las páginas HTML se quedan con max-age=0, must-revalidate. X-Content-Type-Options: nosniff no hace falta: Cloudflare ya lo añade.
Redirecciones y cabeceras se prueban en local con wrangler dev, que sirve dist/ con las mismas reglas, antes de subir nada.
SEO sin plugins
Todo sale de las plantillas, sin plugin:
- JSON-LD:
BlogPostingen cada entrada (coninLanguage,articleSection,keywordsy el logo del editor),WebSiteconSearchActionen la portada,Personen/about/yCollectionPageconItemListen cada serie. - Sitemap con
lastmodpor URL y sin las páginas de paginación. noindexmientras el sitio es una copia de evaluación, controlado por una sola bandera (SITE.indexable), y siempre en la 404./llms.txt: una sección por serie con título y extracto de cada entrada, para agentes.- Tarjeta social por defecto de 1200×630, generada con un Chromium sin interfaz a partir de una página HTML con las fuentes del sitio.
Un fallo que solo se ve comparando
108 de 147 artículos tenían dateModified anterior a datePublished. La fecha de actualización venía de la página de origen (11/10) y la de publicación era la programada (hasta mayo de 2027). Ahora la fecha de modificación es max(date, updated).
Lo que pesa de verdad
Medido con Chromium y la caché desactivada, sobre el sitio publicado y con una sola pasada por página: un orden de magnitud, no un benchmark.
| Página | Peticiones | Transferido | LCP |
|---|---|---|---|
| Portada | 13 | 192 KB | 265 ms |
| Entrada | 10 | 170 KB | 160 ms |
| Entrada, con el buscador abierto | 14 | 221 KB | 150 ms |
Desglose de una entrada: las fuentes son el 81 % (cuatro ficheros, 138 KB), el HTML pesa 12 KB, la hoja de estilos 5 KB y el JavaScript propio es 0: los dos scripts del sitio (buscador y tooltip) van dentro del HTML, unos 2 KB. Los 10 KB de «Script» son el beacon de Cloudflare Web Analytics, no del sitio. Abrir el buscador añade unos 50 KB, pagados solo por quien lo usa.
Las tres fuentes de texto se precargan (<link rel="preload" as="font">) para que no lleguen después de la hoja de estilos y desplacen el texto.
El día del cambio
El 22 de noviembre de 2026 se apagó WordPress. Se hizo en cuatro fases, cada una con su comprobación y su vuelta atrás, y con un script que repite las mismas ~45 comprobaciones antes y después (scripts/preflight.mjs: las 63 entradas, las 76 URL antiguas, las 157 redirecciones una a una, 656 imágenes antiguas, la indexación y las cabeceras).
- Backup final de WordPress: 796 filas de
wp_postsen el dump, las mismas que la base de datos viva, y una copia fuera de la rotación. - Desplegar el sitio como indexable.
- Cambiar el dominio en Cloudflare.
- Apagar WordPress, sin borrarlo: contenedores parados y con
restart=no, y los datos guardados 30 días.
Tres cosas que conviene saber si haces algo parecido:
- WordPress se servía cacheado un año en el borde (
s-maxage=31536000, por un plugin de caché de página). Cambiar el origen sin purgar la caché de Cloudflare y sin borrar las reglas que el plugin había creado habría seguido entregando las páginas viejas. - Apagar los contenedores no basta: tenían
restart: always, y sindocker update --restart=nohabrían vuelto a arrancar tras el siguiente reinicio. - Dos tropiezos reales, que la comprobación automática encontró: durante unos minutos la web real se sirvió con
noindex, porque el interruptor estaba en otra rama que aún no se había desplegado; ywwwestuvo unas horas sin registro DNS. Por eso el script mira indexación y redirecciones y no solo que «cargue».
Desde entonces, una Action comprueba cada día que la entrada que toca está en línea, y otra repite la batería completa cada lunes y avisa por Telegram si algo falla.
Troubleshooting
| Síntoma | Causa | Comprobación |
|---|---|---|
El despliegue añade @astrojs/cloudflare y falla |
No hay wrangler.jsonc y Wrangler autoconfigura |
Crear el fichero con assets.directory |
markdown.rehypePlugins … run on the unified processor |
Astro 7 usa Sätteri; remark/rehype ya no vienen instalados | Portar a hastPlugins, o instalar @astrojs/markdown-remark |
cannot set property 'href' on a 'element' node |
setAttribute es para MDX/JSX |
ctx.setProperty(node, 'href', …) |
/serie da 404 pero /serie/ redirige |
La regla de _redirects solo casa la ruta exacta |
Emitir la variante sin barra |
| Una tabla o un diagrama desaparece tras una admonición | El <div> HTML se continúa hasta una línea en blanco |
Línea en blanco tras </div> |
| La entrada de las 9:00 no salió | El cron de GitHub se retrasó o se descartó |
gh workflow run; varios disparos y una sonda idempotente |
El beacon de Web Analytics no aparece con curl |
Cloudflare solo lo inyecta si pides HTML | curl -H 'Accept: text/html' |
The language "cisco" doesn't exist, falling back to "plaintext" |
Shiki no incluye ese lenguaje | langAlias si hay uno equivalente; si no, texto plano |
| Los enlaces internos de un artículo no llevan a la sección | El id del encabezado tiene tildes y el índice no |
Emitir el id explícito, sin tildes |
| Las líneas de los bloques de código salen muy separadas | Shiki marca cada línea con class="line" y tu CSS también usa .line |
Renombra tu clase y mira en las herramientas del navegador qué CSS recibe una línea de código |
El comando que más ahorra: reproducir el sitio de producción en local, con las mismas reglas.
npm run build && npx wrangler dev --port 8799
curl -sI http://127.0.0.1:8799/devsecops # 301, no 404
Buenas prácticas
- Un único punto de verdad para «qué está publicado» (
allPosts()), y un guardia al final del build que lo compruebe leyendo los ficheros, no el código. - Todo lo que dependa de la hora debe ser idempotente. Si el cron falla, repetir el disparo no puede hacer daño.
- Prueba en un navegador real. El área de toque, que las fuentes no se descarguen dos veces tras precargarlas y que Pagefind no se pida hasta usarlo se comprobaron ahí, no leyendo el código.
- Compara antes y después cuando generes contenido: número de páginas, encabezados, tablas, imágenes y enlaces. Así salió el
dateModifiedanterior a la publicación y la tabla tragada por una admonición. - No pagues por lo que no usas. El buscador se pide al abrirlo; las fuentes, solo las del subconjunto latino.
- Deja el servidor fuera del camino crítico. Si el repo de contenido está caído, el sitio sigue sirviendo el último
dist/.
Referencias
- Astro — colecciones de contenido · Rutas (ficheros con
_) · Markdown - Astro 7 — guía de actualización · Sätteri
- Astro —
@astrojs/sitemap· Despliegue en Cloudflare - Pagefind — indexado · filtros · interfaz
- Cloudflare — redirecciones de static assets · cabeceras · límites
- Cloudflare — Workers Builds · Web Analytics
- GitHub Actions — el evento
schedule - schema.org — BlogPosting · Google — datos estructurados de artículos
- FastAPI · React · Flutter