Creación de Sitios de Documentación con Docusaurus

Necesitas un sitio de documentación para tu biblioteca, framework o producto SaaS. Lo quieres estático, rápido y fácil de mantener sin tener que construir todo desde cero. Docusaurus v3 maneja esto bien—es un generador de sitios estáticos maduro basado en React que incluye versionado, integración de búsqueda y soporte para MDX de forma nativa.

Esta guía cubre la arquitectura y configuración práctica de un sitio de documentación con Docusaurus, enfocándose en conceptos que permanecen estables a través de versiones menores.

Arquitectura Principal de un Sitio de Documentación con Docusaurus

Docusaurus organiza el contenido en tres tipos de contenido distintos:

Docs viven en el directorio /docs. Estas son tus páginas de documentación principales, renderizadas con navegación automática en la barra lateral y soporte para versionado. Cada archivo Markdown o MDX se convierte en una página.

Las publicaciones de Blog van en /blog. Estas funcionan bien para registros de cambios, anuncios de lanzamiento o tutoriales que son sensibles al tiempo.

Las Pages en /src/pages son componentes React independientes o archivos MDX para páginas de inicio personalizadas, secciones “acerca de” o cualquier cosa fuera de la estructura docs/blog.

La barra lateral y el modelo de versionado merecen atención. Docusaurus genera automáticamente barras laterales desde tu estructura de carpetas, o puedes definirlas explícitamente en sidebars.js. Cuando creas una versión, toma una instantánea de tus docs actuales en versioned_docs/, permitiendo a los usuarios acceder a la documentación de versiones anteriores.

Configuración de Docusaurus v3: Primeros Pasos

El scaffolding moderno soporta npm, Yarn, pnpm y Bun. Elige el que use tu equipo:

npx create-docusaurus@latest my-docs classic

El preset classic agrupa el plugin de docs, el plugin de blog y el tema predeterminado—suficiente para la mayoría de los sitios de documentación para desarrolladores. Docusaurus v3 requiere Node.js 20 o posterior para desarrollo local y CI.

Después del scaffolding, la estructura de tu proyecto se ve así:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

El archivo docusaurus.config.js controla los metadatos del sitio, configuración del tema, navbar, footer y opciones de plugins. Este único archivo maneja la mayoría de la personalización sin tocar código React.

Documentación MDX: Escribiendo Contenido

Docusaurus v3 usa MDX v3, que es más estricto que las versiones anteriores. Esto importa si estás migrando desde v2—MDX v3 aplica sintaxis JSX apropiada y no ignorará silenciosamente componentes mal formados.

Cada archivo de documentación soporta frontmatter para metadatos:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

Puedes incrustar componentes React, usar diagramas de Mermaid e incluir bloques de código interactivos. El alias @site apunta a la raíz de tu proyecto para las importaciones.

Para diagramas, habilita el plugin Mermaid en tu configuración:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

Tematización y Personalización

El sistema de plugins te permite extender funcionalidad sin hacer fork del tema. Los plugins comunes manejan analíticas, sitemaps, soporte PWA y redirecciones.

Para personalización visual, sobrescribe variables CSS en src/css/custom.css. El tema usa Infima internamente, así que estás ajustando tokens de diseño en lugar de escribir estilos de componentes:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

La personalización más profunda usa “swizzling”—extraer componentes del tema para modificarlos. Ejecuta npx docusaurus swizzle para ver los componentes disponibles. Haz swizzle solo de lo que necesites, ya que los componentes extraídos requieren actualizaciones manuales al actualizar Docusaurus.

Integración de Búsqueda

La mayoría de los sitios Docusaurus en producción usan Algolia DocSearch. Solicita el programa gratuito si tus docs son públicos, o auto-hospeda el crawler para documentación privada.

La configuración vive en themeConfig:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 también soporta Algolia AskAI, que añade búsqueda conversacional opcional sobre la experiencia de búsqueda estándar y se configura como parte de la misma integración de Algolia.

Despliegue

Docusaurus construye a HTML, CSS y JavaScript estáticos en el directorio /build. Cualquier hosting estático funciona: Vercel, Netlify, GitHub Pages, Cloudflare Pages o tu propio CDN.

npm run build

La salida es un sitio estático estándar sin requerir runtime de servidor. Configura tu proveedor de hosting para manejar el enrutamiento del lado del cliente sirviendo index.html para rutas desconocidas.

Qué Saber para Producción

Algunas notas prácticas para mantener un sitio de documentación para desarrolladores:

• El versionado añade complejidad. Solo versiona cuando los usuarios genuinamente necesiten acceso a docs antiguos. Muchos proyectos funcionan bien con una única versión “actual”.
• La rigurosidad de MDX detecta bugs reales. Si la migración desde v2 rompe páginas, los errores usualmente apuntan a problemas reales de JSX que vale la pena corregir.
• Los tiempos de construcción escalan con el contenido. Los sitios grandes se benefician de construcciones incrementales en CI y cacheo de node_modules.

Conclusión

Docusaurus maneja la infraestructura para que puedas enfocarte en escribir buena documentación. La base de React significa que los equipos frontend pueden personalizar profundamente cuando sea necesario, mientras que los valores predeterminados funcionan lo suficientemente bien como para que muchos sitios se desplieguen sin tocar código React en absoluto. Comienza con el preset clásico, añade plugins a medida que surjan requisitos y resiste la tentación de sobre-personalizar antes de que el contenido de tu documentación sea sólido.

Preguntas Frecuentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.