En la actualidad, existen más de 400 millones de repositorios de código en plataformas como GitHub. Con un ecosistema tan grande, documentar bien un proyecto se ha convertido en algo crucial para que cualquier desarrollador que quiera usar o revisar el código, pueda comprender su funcionamiento.
Además, una buena documentación también nos permitirá realizar un mejor mantenimiento de nuestro código a largo plazo. Además de agilizar la incorporación de nuevos desarrollos, también mejorará la comprensión de la estructura y la resolución de posibles problemas.
En definitiva, generar documentación en un proyecto es algo fundamental. Para lograrlo, existen varias herramientas especializadas, entre las que destacan MkDocs y Docusaurus. Ambas permiten generar documentación de manera rápida, sencilla y con un acabado profesional, facilitando el acceso a la información y la comprensión de nuestro código.
¿Qué es MkDocs?
Según la documentación oficial, MkDocs es “un generador de sitios estáticos rápido, simple y absolutamente hermoso que está orientado a la creación de documentación de proyectos”. Por tanto, podemos decir que esta herramienta nos ayudará a generar documentación técnica para nuestros proyectos. Además, y de una forma rápida y simple, MkDocs nos permitirá visualizarlos en formato web.
MkDocs está basado en Markdown, lo que permite escribir la documentación de forma muy sencilla y ordenada. En una estructura base, cada uno de los ficheros Markdown representarán las diferentes páginas del sitio web. Esto nos permitirá organizarlo todo de manera estructurada y elegante.
Además, está pensado para poder usarse en todo tipo de proyectos y tiene una curva de aprendizaje muy rápida. Estas cualidades son especialmente útiles en distintos escenarios. Por un lado, para equipos con varios desarrolladores que quieren documentar el código para que el resto de miembros lo entiendan. Y, también, en el caso de programadores individuales que quieren dar a conocer sus creaciones al resto de la comunidad.
Por último, merece la pena destacar que MkDocs está más centrado a la documentación de repositorios de Backend. Esto se debe a que su enfoque centrado en Markdown es óptimo para documentar APIs y arquitecturas de software o de data. Además, al no depender de React o de otros frameworks de Frontend (cosa que, como veremos más adelante, no ocurre con Docusaurus) le permite poder generarlos de manera mucho más rápida, fácil y con una integración directa con herramientas como GitHub pages.
MkDocs: Características principales
Una vez comprendido qué es MkDocs y para qué se utiliza, vamos a hablar de cuáles son sus características principales.
En primer lugar, MkDocs destaca por tener una configuración muy sencilla. Al instalar la herramienta (algo que veremos a continuación), se generarán una serie de archivos que nos facilitarán su configuración, permitiéndonos tenerlo todo listo en apenas unos minutos.
Esto resulta especialmente relevante, ya que reducirá el tiempo invertido en esta configuración inicial. Además, nos dará margen para centrarnos en la creación de la documentación en sí o en el desarrollo del propio aplicativo.
Markdown en MkDocs
Por otro lado, MkDocs está basado en Markdown. Esto es realmente interesante para desarrolladores con pocos conocimientos de HTML o CSS. Gracias a este enfoque, es posible generar el sitio web de la documentación sin necesidad de tener que preocuparse por todo lo relacionado con la maquetación.
Esta característica hace que el proceso de documentación sea mucho más sencillo y nos da pie a centrarnos en su contenido más que en la apariencia o la estructura.
Plugins de MkDocs
Otra particularidad a tener en cuenta es que MkDocs permite incorporar plugins que aumentan sus prestaciones y facilitan la personalización de la documentación. Su instalación es increíblemente sencilla. Únicamente hará falta instalarlos en el repositorio con pip o poetry y añadirlos en la configuración de MkDocs.
Aunque existen muchas más opciones de las que se muestran aquí, algunos de los plugins más comunes y útiles son:
- El plugin mkdocs-mermaid facilita el uso de diagramas en Markdown con sintaxis de Mermaid.
- Con mkdocs-table-reader-plugin se pueden insertar tablas externas en la documentación.
- mkdocs-minify-plugin minimiza el HTML, CSS y JS para mejorar el rendimiento de la documentación.
En cuanto a la integración con plataformas de control de versiones (como, por ejemplo, GitHub), MkDocs permite realizar el despliegue de la documentación directamente en GitHub Pages con un único comando. Esto facilita en gran medida el despliegue de la documentación. Sobre todo, en repositorios con un gran volumen de archivos y ficheros.
De igual manera, mediante su plugin mike, MkDocs también ofrece soporte para múltiples versiones. Gracias a él, es posible gestionar diferentes versiones de la documentación, lo que le aporta robustez y trazabilidad. Esto se debe a que los usuarios podrán acceder a la documentación específica durante todas sus fases del desarrollo.
Por último, y a pesar de que hay bastantes más puntos que se podrían tratar en este apartado, destacaremos que MkDocs cuenta con una variedad de temas prediseñados con los que modificar y personalizar la apariencia del sitio web. Entre todos ellos destaca Material for MkDocs. Además de ser uno de los más populares, da a la página uno estilo elegante, moderno y muy configurable. En el siguiente apartado, veremos la instalación y configuración de Material for MkDocs.
Cómo instalar MkDocs en tu proyecto
A continuación, veremos un tutorial paso a paso para instalar MkDocs en tu proyecto, específicamente mkdocs-material.
En primer lugar, es importante destacar que existen varias formas de realizar la instalación. La elección dependerá del sistema de gestión de paquetes que utilices. En mi caso, dado que normalmente uso poetry para la gestión de dependencias, seguiré este método. No obstante, también es posible instalarlo con pip.
Para añadir MkDocs a tu proyecto y registrarlo en el archivo pyproject.toml, simplemente ejecuta el siguiente comando:
poetry add mkdocs-materialGenerar estructura de documentos en MkDocs
Esto instalará tanto MkDocs como el tema de mkdocs-material. Una vez instalado, ya puedes generar la estructura básica de la documentación de tu proyecto. Para ello, dirígete a la raíz del mismo y lanza el comando:
mkdocs new .Al ejecutarlo, se generará toda la estructura de archivos necesarios para que empieces a crear toda la documentación.
Dado que queremos usar el tema de material, hay que especificar en la configuración que use ese tema en concreto. Para ello, en el fichero mkdocs.yml que se ha generado deberemos incluir el siguiente código:
theme:
name: material
language: es
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: blue grey
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue grey
toggle:
icon: material/brightness-4
name: Switch to light modeCon esto, ya tendremos configurado nuestro MkDocs con material theme para empezar a generar nuestra documentación. Ya solo queda acceder a la carpeta donde se encuentre nuestro fichero de configuración (mkdocs.yml) e inicializar el servicio de desarrollo lanzando:
mkdocs serveEsto ejecutará un servidor local que nos permitirá ver en tiempo real nuestra documentación según la vayamos generando.
Por último, si lo que queremos es generar la documentación en un formato listo para poder desplegarse en un sitio web, ejecutamos:
mkdocs buildEsto creará una carpeta llamada site/ y generará todos los ficheros necesarios para alojar nuestra documentación en un servidor web.
¿Qué es Docusaurus?
Tras haber analizado MkDocs, pondremos sobre la mesa uno de sus principales competidores directos, Docusaurus. Para ello, antes de nada, definamos qué es Docusaurus.
Docusaurus es un generador de sitios estáticos desarrollado por Meta que permite crear páginas webs de documentación de manera rápida y sencilla. Al igual que MkDocs, su enfoque se basa en Markdown. Sin embargo, al estar construido con React, permite realizar una mayor personalización del contenido que se muestra.
De igual manera que hicimos con MkDocs, es importante conocer las características principales que tiene Docusaurus y qué nos ofrece.
Características principales de Docusaurus
Lo primero que hay que mencionar es que, al igual que MkDocs, Docusaurus está basado en Markdown. De este modo, nos permite crear la documentación en este formato. Sin embargo, la gran diferencia con MkDocs es que cuenta con soporte para React. Gracias a ello, podremos integrar componentes de React que, a su vez, permitirán añadir funcionalidades interactivas a nuestra documentación.
Esta característica nos ayudará a agregar elementos como gráficos dinámicos, formularios, tablas interactivas o cualquier otro componente de React que mejore la experiencia de usuario.
Por otro lado, Docusaurus también utiliza un fichero de configuración llamado docusaurus.config.js. Al igual que mkdocs.yml, permite definir la estructura del sitio web y configurar los plugins y los temas de forma rápida e intuitiva.
A continuación, veremos dos características clave en Docusaurus. Por un lado, el soporte para múltiples versiones y, por otro, la internacionalización i18n integrada. Estas funcionalidades, al igual que en el caso de Mkdocs, se pueden integrar y configurar de manera muy simple.
Soporte para múltiples versiones
En cuanto al soporte para múltiples versiones, Docusaurus lo ofrece de forma nativa. Esto permite gestionar diferentes versiones de la documentación de forma más sencilla y facilita la consulta de cambios a lo largo del desarrollo. Todo ello, sin afectar a la versión más reciente.
Uno de los puntos más relevantes en este apartado es que, a diferencia de MkDocs (donde para obtener esta funcionalidad se ha de instalar el plugin mike), Docusaurus integra esta funcionalidad de manera nativa. No necesita realizar ninguna instalación extra y, por tanto, simplifica el proceso y reduce la configuración requerida.
Internacionalización integrada
En cuanto a la internacionalización integrada (i18n), otra gran ventaja de Docusaurus frente a Mkdocs es que lo integra nativamente. Esto facilita la traducción de la documentación a diferentes idiomas sin depender de herramientas externas.
También hay que mencionar otra de las grandes fortalezas de Docusaurus. Al estar construido con React, permite personalizar los estilos y la apariencia del sitio de manera mucho más sencilla que con MkDocs. Docusaurus no solo facilita la gestión de los estilos de toda la página mediante css y temas personalizados. Además, permite incorporar componentes de React, otorgándole con ello una versatilidad difícil de alcanzar por otras herramientas.
Aparte de todo lo mencionado, existen otras funcionalidades clave que diferencian a Docusaurus del resto de herramientas. Por ejemplo, tiene soporte para crear y gestionar un blog dentro de la documentación. Esto puede resultar muy interesante cuando hay un equipo grande trabajando en el aplicativo y se necesita documentar el proceso de desarrollo de cada uno de los miembros. Además, Docusaurus genera metadatos automáticamente con los que optimizar el SEO de las páginas de la documentación.
Para terminar, Docusaurus, al igual que MkDocs, cuenta con integración directa con GitHub Pages y otros servicios de despliegue como Vercel, Netlify y Cloudflare Pages. Además, cuenta con un ecosistema de plugins (tanto oficiales como de la comunidad) que se pueden instalar para ampliar sus funcionalidades.
En definitiva, Docusaurus también es una herramienta muy completa para la generación de documentación en proyectos de software. Las distintas funcionalidades que posee la hacen especialmente relevante para desarrollos de la parte frontend de una aplicación.
Instalación de Docusaurus paso a paso
Llegados a este punto, lo siguiente que haremos será instalar Docusaurus en nuestro proyecto.
En primer lugar, y dado que necesita de Node.js para funcionar, debemos asegurarnos de que está instalado en nuestro sistema. Para ello, ejecutaremos el siguiente comando:
node -vSi Node.js está correctamente instalado, este comando nos devolverá la versión que hay en nuestro sistema. Si no lo está, tendremos que instalarlo siguiendo las instrucciones de la página oficial de descarga de Node.js.
Una vez estemos seguros de que está instalado en nuestro sistema, el siguiente paso será lanzar este comando en la terminal para instalar Docusaurus:
npx create-docusaurus@latest docCon él, estamos utilizando npx para ejecutar el paquete create-docusaurus@latest, que instalará la última versión disponible de Docusaurus y la estructura base del proyecto. Esto generará todos los archivos necesarios dentro de la carpeta que hemos especificado. En este caso, docs.
Instalación de templates
A la hora de la instalación, existen diferentes templates de los que tendremos que elegir en función de nuestras necesidades.
- classic. Opción recomendada si quieres empezar rápidamente y sin configuraciones extra.
- git repository. Esta opción es la recomendada si ya tienes una plantilla en un repo de git.
- local template. Por último, si quieres usar una plantilla que tengas en tu ordenador, podrás seleccionar esta opción.
Por último, te pedirá elegir entre JavaScript o TypeScript para tu configuración, dependiendo de tus preferencias de desarrollo.
Además, si ya sabes cual es la configuración que quieres en tu proyecto, podrás lanzarlo todo con un único comando. Por ejemplo:
npx create-docusaurus@latest doc classic --typescriptEsto generará toda la arquitectura necesaria para poder empezar a desarrollar la documentación de tu proyecto.
Una vez finalizada la instalación, ya solo nos quedará acceder al directorio del proyecto e iniciar el servidor de desarrollo mediante el siguiente comando.
npm run startAl igual que con MkDocs, si queremos generar la documentación en un formato listo para poder desplegarse en un sitio web, solo tendremos que lanzar:
npm run buildMkDocs y Docusaurus: Comparativa técnica
Llegados a este punto en el que ya conocemos las características de ambas herramientas y cómo instalarlas, el siguiente paso es hacer una comparativa directa para ver cuál se adapta mejor a los diferentes proyectos.
Para ello, se plantearán diferentes cuestiones que y se irá designando un ganador en la comparativa en caso de que lo hubiera.
Facilidad de instalación y configuración
Tanto MkDocs como Docusaurus se instalan con dos simples comandos de terminal. Sin embargo, hay una diferencia clave, que es que para poder instalar Docusaurus has de tener instalado Node.js previamente. En caso de tener que descargarlo e instalarlo en tu sistema, aporta una mayor complejidad a la instalación.
Por esa razón, y aunque ambos a priori son muy similares en cuanto a la dificultad de instalación, MkDocs ofrece una experiencia más sencilla. Por tanto, le daríamos como ganador en este apartado.
Ganador: MkDocs
Curva de aprendizaje
En cuanto a la dificultad que vamos a tener para dominar la herramienta y poder sacarle todo su potencial, hay que reconocer que MkDocs es sustancialmente más fácil de utilizar que Docusaurus.
Por un lado, MkDocs se basa completamente en Markdown y su configuración se realiza mediante un único archivo. Aunque Docusaurus también permite escribir la documentación en formato Markdown, hay que añadirle una complejidad adicional al tener en cuenta que es necesario contar con conocimientos de JavaScript y React para aprovechar totalmente su personalización.
Por esa razón, en este caso también damos como ganador a Mkdocs. Aunque la curva de aprendizaje de ambos es relativamente baja, Docusaurus requiere un mayor conocimiento y tiempo de adaptación para sacar todo su potencial.
Ganador: MkDocs
Flexibilidad y personalización
En este apartado hay un claro ganador, Docusaurus.
Docusaurus está específicamente diseñado para otorgar al desarrollador mayor flexibilidad y personalización de todas las páginas. Como hemos comentado anteriormente, esto se debe a que al estar basado en React. Esto permite modificar no solo los estilos, sino también la funcionalidad de cada una de las páginas.
Por otro lado, MkDocs, aunque permite algo de personalización especialmente mediante temas y plugins especializados, ofrece una menor capacidad de personalización. Es, con diferencia, una herramienta menos versátil en este punto.
Ganador: Docusaurus
Soporte para múltiples idiomas
De acuerdo, continuemos con la comparativa centrándonos ahora en cuál de las dos herramientas ofrece un mayor soporte para múltiples idiomas, es decir i18n.
Por un lado, ambas permiten gestionar la documentación en diferentes idiomas, lo que en cualquier caso, facilita la creación de versiones traducidas en caso de necesitarlo en nuestro proyecto. Sin embargo, mientras que MkDocs necesita que instalemos un plugin externo llamado mkdocs-static-i18n para poder tener esta funcionalidad, con la respectiva configuración extra requerida, Docusaurus lo incorpora de forma nativa, teniendo únicamente que definir los idiomas en el fichero de configuración docusaurus.config.js para que estos se generen automáticamente.
Por esa razón, dado que lo incorpora de manera nativa y con una configuración más sencilla, en este apartado también vence Docusaurus.
Ganador: Docusaurus
Rendimiento
Pasemos a hablar del rendimiento. Este punto es sumamente importante cuando queremos generar documentación de un proyecto relativamente grande.
Por un lado, como MkDocs está basado en Python, permite generar los sitios estáticos extremadamente rápido. Gracias a esta capacidad, no requiere del uso de frameworks externos que ralentizan todo el proceso.
Por otro lado, como Docusaurus está basado en React y Javascript. Por tanto, tendrá que usar más recursos para generar y visualizar el sitio, sobre todo, y tal y como ya hemos visto, si éste es especialmente grande. Una mayor complejidad demandará más tiempo y recursos a la hora de realizar todas las tareas necesarias para su generación.
En definitiva, la tecnología base que usan ambas herramientas es un punto clave en su rendimiento y por esa razón en este apartado MkDocs es el claro vencedor.
Ganador: MkDocs
Soporte para temas y estilos personalizados
Es lógico pensar que si en flexibilidad y personalización Docusaurus tuvo una clara ventaja, en este apartado, también debería de tenerla. Y ya te adelanto que es así.
Es cierto que MkDocs permite usar temas predefinidos y modificarlos mediante CSS. Por otro lado, y como ya hemos comentado, cuenta con el tema de Material for MkDocs que le otorga unos estilos minimalistas y elegantes. Sin embargo, estos temas y mejoras que se pueden realizar no alcanzan el nivel de flexibilidad que React le aporta a Docusaurus.
Gracias a React, Docusaurus no solo es capaz de modificar la documentación generada mediante CSS, temas personalizados o incluso componentes custom. Además, permite un control total sobre los temas y estilos. Esta cualidad le proporciona una ventaja insalvable para otras herramientas como Mkdocs.
Ganador: Docusaurus
Integración con otras tecnologías
Como hemos visto anteriormente, es importante tener una buena documentación en tu proyecto. En caso de que dicha documentación no pudiera integrarse con plataformas como GitHub Pages u otras similares, su alcance y utilidad serán mucho menor. Por esa razón, es tan relevante que estas herramientas ofrezcan una integración sencilla y directa con estos servicios.
En este caso, tanto MkDocs como Docusaurus permiten integrarse de manera nativa con estas plataformas. Además, ambas generan archivos estáticos que se enlazan automáticamente una vez se hayan configurado correctamente.
Por lo tanto, dado que ambas se integran de manera nativa con estas herramientas y tienen la misma facilidad de implementación, se puede considerar que hay un empate en este apartado.
Ganador: Empate
Mantenimiento y comunidad de desarrolladores
Por último, nos centraremos en cuál de las dos herramientas tiene un mayor mantenimiento y una comunidad más grande y activa.
Cabe destacar que Docusaurus, al estar desarrollado y mantenido por Meta, tiene un equipo más dedicado y que ofrece un soporte oficial que otras herramientas, incluido MkDocs, no tienen. Además, al estar basado en React, hace que su comunidad sea cada vez mayor y que las aportaciones y actualizaciones sean mucho más frecuentes.
Por otro lado, aunque la comunidad que tiene MkDocs también es representativa, por razones obvias, no puede llegar al nivel de la que ofrece Docusaurus con una empresa del tamaño de Meta dando soporte por detrás. Por eso, a pesar que se realiza el mantenimiento de las versiones y la implementación de nuevos desarrollos a un ritmo nada despreciable, en perspectiva, no se puede comparar con las que ofrece Docusaurus.
Ganador: Docusaurus
MkDocs o Docusaurus, ¿cuál elegir según el tipo de proyecto?
Una vez llegados a este punto, tras analizar qué son MkDocs y Docusaurus por separado y compararlos entre sí, podemos ver que no hay un claro ganador en todos los apartados. El uso de una u otra herramienta dependerá de las necesidades del proyecto que estamos llevando a cabo.
Por lo tanto, el siguiente paso es comprender cuándo es mejor usar uno u otro.
Cuándo usar MkDocs
Si necesitas una documentación rápida y sencilla, que te aporte todos los beneficios de tener documentado tu proyecto sin la necesidad de dedicarle mucho tiempo y esfuerzo al proceso, MkDocs es tu herramienta.
Con ella, podrás generar toda la información en Markdown de manera muy sencilla. Además, hay una gran cantidad de plugins que van a permitirte enriquecer mucho tus páginas sin la necesidad de realizar una configuración y personalización excesiva. Por otra parte, podrás integrarlo con GitHub Pages sin apenas esfuerzo.
En definitiva, si tu desarrollo es en Python (como puede ser el backend de una aplicación o un proyecto de Data) y buscas una solución ligera, eficiente y fácil de mantener, MkDocs es tu mejor opción.
Cuándo se utiliza Docusaurus
Dadas sus características, Docusaurus va a ser la opción a elegir si buscas generar documentación para un aplicativo hecho con React. Es decir, para la parte frontend de una aplicación.
Gracias a su integración con React, permite enriquecer y personalizar la documentación con componentes propios, dando una mayor visibilidad y mejorando el estilo de la misma. Además, posibilita de manera nativa generar un blog donde distintos desarrolladores podrán subir sus aportaciones o diferentes tutoriales. Y, si ya estás familiarizado con React, tanto la configuración del sitio como su personalización te resultarán muy sencillos.
Por lo tanto, si estás desarrollando la parte frontend de un aplicativo y tu prioridad es tener una documentación muy personalizada, con elementos interactivos y unos estilos dinámicos que hagan única tu página, Docusaurus es tu mejor opción.
Conclusión
Como hemos podido observar a lo largo de todo el artículo, tanto MkDocs como Docusaurus son dos herramientas muy potentes. Ambas permiten generar documentación bien estructurada en formato Markdown y de manera rápida, intuitiva y con una gran cantidad de opciones.
Cada una tiene sus ventajas e inconvenientes, por lo que la elección de una u otra dependerá de las necesidades de tu proyecto. Sin embargo, gracias a MkDocs y Docusaurus ya no hay excusas para no generar una documentación clara de tu proyecto. Gracias a ellas, el contenido será mucho más comprensible para el resto de desarrolladores y también mejorará la colaboración y el mantenimiento a largo plazo.
¡Esto es todo! Si este artículo te ha parecido interesante, te animamos a visitar la categoría Software para ver todos los posts relacionados y a compartirlo en redes. ¡Hasta pronto!
