Docusaurus

Qué es

Docusaurus es un generador de sitios estáticos (static site generator) creado y mantenido por Meta (Facebook), pensado específicamente para construir webs de documentación. Está construido con React y usa MDX, lo que permite escribir el contenido en Markdown e insertar componentes de React dentro de las páginas. Es un proyecto de código abierto muy activo (versión 3.10.1 a fecha de 2026) bajo licencia MIT.

Para qué sirve

• Publicar la documentación de una librería, framework o producto con buscador, modo oscuro y navegación lateral ya integrados.
• Mantener varias versiones de la documentación a la vez (versioning), útil cuando conviven distintas releases de un proyecto.
• Ofrecer la documentación en varios idiomas gracias a su sistema de internacionalización (i18n) incorporado.
• Añadir un blog al sitio, ideal para changelogs o notas de versión.
• Integrar búsqueda mediante Algolia DocSearch sin tener que programarla.

Cuándo usarlo

Es la opción ideal cuando necesitas un sitio de documentación que se mantenga fácilmente escribiendo en Markdown, pero quieres poder extenderlo con componentes React cuando haga falta. Encaja especialmente bien en proyectos open source y en equipos que ya trabajan con el ecosistema React. Si solo buscas notas simples sin personalización, alternativas como MkDocs (Python) o VitePress (Vue) pueden ser más ligeras; si necesitas un sitio web completo más allá de la documentación, un framework general como Astro o Next.js te dará más libertad.

Ejemplo

Crear un nuevo sitio de documentación y arrancarlo en local:

# Crear el proyecto con la plantilla clásica
npx create-docusaurus@latest mi-web classic

cd mi-web

# Arrancar el servidor de desarrollo
npm run start

A partir de ahí, basta con añadir archivos Markdown dentro de la carpeta docs/. Para insertar un componente de React en una página .mdx:

---
title: Mi primera página
---

import BotonDestacado from '@site/src/components/BotonDestacado';

# Hola Docusaurus

Esto es Markdown normal, pero también puedo usar componentes:

<BotonDestacado>Pulsa aquí</BotonDestacado>

Para generar la versión estática lista para desplegar:

npm run build

Puntos clave

• Basado en React y MDX: combina la sencillez de Markdown con la potencia de los componentes.
• Versionado y traducción de la documentación incluidos de serie.
• Búsqueda integrada con Algolia y modo oscuro por defecto.
• Arquitectura de plugins y temas que permite personalizar y extender el sitio.
• Genera HTML estático optimizado, fácil de desplegar en GitHub Pages, Netlify o Vercel.

Ten en cuenta

• Requiere conocer (o estar dispuesto a aprender) algo de React si quieres personalizar más allá de lo básico; para sitios muy simples puede resultar excesivo.
• Las actualizaciones de versión mayor (por ejemplo de v2 a v3) pueden implicar migraciones de configuración.
• Está enfocado a documentación: para una web corporativa o una aplicación completa hay opciones más generalistas (Astro, Next.js).
• Alternativas a considerar según tu stack: MkDocs/Material para Python, VitePress para el ecosistema Vue.