¿Por qué Docusaurus? 🦖
¡Hola, amigos! ✌️
Docusaurus es un framework de documentacion hecho en React 🦖⚛️.
Toda la documentacion se escribe en Markdown (.md) es decir, es como hacer un README en Github.🐙
¿Por elegí Docusaurus para llevar acabo la documentación del sistema? 💡
Antes de poner manos a la obra, me puse a buscar formas más modernas y eficientes de hacer la documentación. Descubrí que frameworks como Docusaurus o VuePress son muy utilizados por empresas y proyectos destacados, por lo que me parece una alternativa mucho más óptima para nuestro sistema. 🖥️
¿Cuales son sus pros? ✅
Su enfoque principal es facilitar la escritura, organización y despliegue de documentación para proyectos de software, APIs, librerías o sistemas completos, usando Markdown y React. ⚛️
La documentación es basada en Markdown y es muy sencillo de usarGenera un sitio web de documentación modernoDocumentación organizada, clara y diseño limpioEscalableProfesionalismoMucha documentacion y plugins ya listosDiseño del sistema
Comparativa Docusaurus vs VuePress ✅
| Característica | Docusaurus | VuePress |
|---|---|---|
| Framework base | React | Vue.js |
| Lenguaje principal | JavaScript / JSX / React | JavaScript / Vue |
| Facilidad de inicio | Muy rápido si conoces React; plantillas listas para docs | Rápido si conoces Vue; plantillas simples |
| Estructura de docs | Carpetas docs/, blog/, src/pages/, sidebar configurado en sidebars.js | Carpetas docs/, components/; sidebar definido en config.js |
| Sidebar & Navegación | Muy flexible: categorías, subcategorías, índices generados automáticamente | Flexible, requiere más configuración manual para subcategorías |
| Soporte Markdown/MDX | Markdown + MDX (puedes usar componentes React dentro) | Markdown nativo; componentes Vue con *.vue o slots especiales |
| Blogs y versiones | Integrado; soporta múltiples versiones de docs de forma nativa | Blog no integrado; versiones requieren plugins externos o manejo manual |
| Plugins / Extensiones | Ecosistema grande de plugins oficiales y comunidad (SEO, búsqueda, Google Analytics, etc.) | Ecosistema bueno pero más pequeño; muchos plugins no oficiales |
| Tema / Personalización | Temas listos (claro/oscuro), personalizable con CSS y componentes React | Temas listos básicos; personalización vía Vue y CSS |
| Despliegue | Compatible con GitHub Pages, Netlify, Vercel, Docker, etc. | Compatible con GitHub Pages, Netlify, Vercel, Docker |
| Caché y build | Build rápido con Webpack; caché incremental | Build rápido con Vite (VuePress 2); caché incremental |
| Popularidad | Muy usado por proyectos grandes como React, Facebook, Stripe | Popular en proyectos Vue y comunidad open source de Vue |
| Pros | Fácil versionado, MDX con React, integración con blogs, muy bien documentado | Ligero, rápido, integración natural con proyectos Vue, Markdown simple |
| Contras | Dependes de React; si tu proyecto no usa React puede ser más pesado | Menos soporte oficial para blogs y versiones; MDX equivalente más limitado |
Si nuestra documentación sigue creciendo, Docusaurus nos da más out of the box
