Generadores de Sitios Estáticos & Docs

Qué incluye este pack

Este pack reúne los cinco frameworks de sitio estático que han sobrevivido al churn de frameworks JS y traen suficientes features para ser opción default en 2026. La lista tiene opinión: nada aquí es un proyecto hobby de "generamos HTML desde un único Markdown" — cada entrada tiene un ecosistema real de plugins, una historia de búsqueda y un setup de producción desplegable.

El set cubre cuatro formas: documentación de desarrollador (VitePress, Docusaurus), páginas de marketing pulidas (Astro), docs-as-a-service hospedado (Mintlify) y presentaciones que los ingenieros realmente quieren dar (Slidev). Un pack, cuatro formatos de salida — elige el que se ajuste a tu audiencia.

Por qué este stack

Los sitios estáticos están de vuelta porque las alternativas resultaron caras. Next.js server-rendered para páginas de marketing cuesta más en cómputo y complejidad que generar HTML al construir. Estos cinco generadores hacen lo mismo: toman Markdown (o MDX) más algo de config y producen HTML estático que puedes hostear en cualquier CDN.

Donde difieren:

• VitePress trae un tema "docs" que se ve correcto out-of-the-box. Usado por Vue, Vite, Vitest mismos — señal fuerte de dogfood.
• Astro es el más amplio. Puede construir un sitio de docs, pero también una landing, un blog, un sitio de marketing pequeño. La arquitectura "Islands" significa que envías cero JS a menos que un componente opte.
• Mintlify es la única entrada hospedada. Escribes Markdown, empujas a GitHub y Mintlify hospeda los docs renderizados en <tu>.mintlify.app (o tu dominio). Es un reemplazo SaaS para autoejecutar Docusaurus.
• Docusaurus es el más pesado pero tiene más plugins — docs versionados, i18n, búsqueda, blog, todo de primera clase. Elígelo cuando necesites versionado entre releases mayores.
• Slidev es el comodín. Slides Markdown-driven con resaltado de código, componentes interactivos y notas de presentador. Los ingenieros que odian Keynote lo aman.

Instala en un comando

# Instala el pack — pone una plantilla starter para cada builder en tu proyecto
tokrepo install pack/static-site-docs

# O elige uno
tokrepo install vitepress
tokrepo install astro
tokrepo install docusaurus

El TokRepo CLI esqueletea cada framework en sites/<framework>/ para que compares output y elijas un ganador antes de comprometerte. Los cinco incluyen un archivo .tokrepo/ con los targets de deploy producción que hemos validado (Vercel, Cloudflare Pages, Netlify, GitHub Pages).

Trampas comunes

• VitePress está atado a Vue. Los componentes custom deben ser Vue. Si tu equipo es React-only, VitePress se sentirá hostil — Docusaurus o Mintlify son las opciones React.
• La hidratación MDX de Astro es opt-in. Un <Counter client:load /> envía JS; un <Counter /> simple no. Olvidar client:* es el bug #1 "por qué no funciona mi botón".
• Mintlify significa lock-in SaaS. Tu contenido es tuyo (todo es Markdown en tu repo) pero el rendering, search y analytics viven en Mintlify cloud. Planea un camino de exportación antes de comprometerte.
• Los docs versionados de Docusaurus son one-way. Una vez que cortas docs versión 2.0, editarlos retroactivamente es incómodo. Sé deliberado sobre cuándo versionar.
• Las decks de Slidev no son slides.dev.com. Son tu repo. El hosting es asunto tuyo (Vercel funciona bien). No intentes compartir una URL localhost con tu CEO cinco minutos antes de un board.

Conceptos erróneos comunes

"Estático significa muerto" es un mito. Los cinco frameworks soportan hidratación, server functions o rendering híbrido para las partes que lo necesitan. Astro puede optar por SSR por ruta; Docusaurus tiene React client-side para interactividad; VitePress corre Vue en el browser para cualquier página que lo necesite. El default es "envía HTML"; el escape hatch es "envía JS donde se gane su peso."

"Todos los generadores estáticos son iguales" también es falso. La elección entre VitePress y Docusaurus determina quién puede contribuir a tus docs (gente Vue vs React). La elección entre Astro y Mintlify determina quién posee el pipeline de deploy (tú vs Mintlify). Elige deliberadamente.