Documenta tus proyectos con Hudocs

Hudocs simplifica la creación de documentación con Hugo, sin Node.js, dependencias adicionales ni complejos procesos de despliegue.

Documentar es tedioso, pero muy importante para que otras personas puedan entender tu código, utilizarlo y colaborar en él. Por eso he creado Hudocs, un tema para Hugo diseñado para facilitar la documentación de proyectos mediante archivos Markdown y una estructura de contenido sencilla.

Hudocs puede utilizarse tanto para proyectos que mantienen una única versión de su documentación como para aquellos que necesitan conservar varias versiones de un mismo producto, generando automáticamente su navegación, buscador y selector de versiones.

Características

Hudocs es un tema para Hugo publicado bajo la licencia MIT y construido utilizando las capacidades nativas de Hugo Extended, sin necesidad de Node.js ni de complejos procesos de compilación. Algunas de sus principales características son:

• Soporte para documentación de una o múltiples versiones
• Sin Node.js, package.json ni node_modules
• Compilación mediante el pipeline nativo de Hugo
• Buscador local avanzado basado en FlexSearch
• Soporte para múltiples idiomas mediante las funciones de internacionalización de Hugo
• Tema claro y oscuro
• Seis temas Duotone integrados para bloques de código
• Shortcodes para pasos, tabs, anotaciones, tipos de datos, alertas, botones, enlaces y columnas
• Soporte para blogs, paginación, tarjetas de posts y RSS
• Asistente de IA con acciones para ChatGPT y Claude
• Navegación multinivel y árbol de documentación configurable
• Tabla de contenidos adaptable para dispositivos móviles
• Hooks nativos de Hugo para encabezados, imágenes, enlaces y tablas
• Alta personalización mediante variables y assets/scss/_custom.scss
• Optimizado para rendimiento y Core Web Vitals
• Nivel de seguridad A+ en Mozilla Observatory

Requisitos

Para utilizar Hudocs necesitas tener instalados Hugo en su versión extendida y Git. En concreto:

• Hugo Extended 0.164.0 o superior
• Git

Instalación

Para instalar Hudocs, ve a la raíz de tu proyecto Hugo y añádelo como submódulo de Git:

git submodule add https://github.com/zkreations/hudocs themes/hudocs

Estructura de documentación

Hudocs adapta automáticamente su funcionamiento según la estructura de directorios que utilices dentro de content/docs/.

Una sola versión

Si tu proyecto mantiene una única versión de documentación, coloca los archivos directamente dentro de content/docs/:

content/
└── docs/
    ├── _index.md
    ├── getting-started.md
    └── configuration.md

En este modo la navegación y las URLs permanecen simples y no se muestra un selector de versiones.

Múltiples versiones

Si necesitas conservar la documentación de diferentes versiones de un producto, cada versión debe ser una subcarpeta dentro de content/docs/:

content/
└── docs/
    ├── latest/
    │   ├── _index.md
    │   └── ...
    ├── 1.8/
    │   ├── _index.md
    │   └── ...
    └── 1.0/
        ├── _index.md
        └── ...

Hudocs genera automáticamente un árbol de navegación, índice de búsqueda y selector independientes para cada versión dentro del mismo proyecto.

Ejemplo

El tema incluye un exampleSite que puedes utilizar como punto de partida. Para copiar su contenido a tu proyecto ejecuta:

cp -R themes/hudocs/exampleSite/content .

También puedes utilizar su archivo de configuración como referencia:

cp themes/hudocs/exampleSite/hugo.toml .

Configurar

Hudocs incluye diferentes opciones para personalizar el comportamiento de la documentación, la navegación, el buscador, el blog, el asistente de IA y otros componentes.

Puedes utilizar el archivo exampleSite/hugo.toml como referencia y adaptar sus valores a tu proyecto.

Después de configurar el tema, inicia el servidor local con:

hugo serve

Personalizar

Hudocs permite personalizar sus estilos sin modificar directamente los archivos del tema. Crea el archivo assets/scss/_custom.scss en la raíz de tu proyecto y coloca allí tus estilos personalizados.

Esta es también la ubicación recomendada para sobrescribir los estilos del tema y adaptar su apariencia a las necesidades de tu proyecto.

Shortcodes

El tema incluye diferentes shortcodes para ampliar las posibilidades de Markdown:

• {{< steps >}} para guías paso a paso numeradas
• {{< tabs >}} y {{< tab >}} para contenido con pestañas
• {{< annotated >}} para combinar código, tabs o tablas con anotaciones
• {{< types >}} para mostrar tipos de datos y estructuras de parámetros
• {{< hint >}} para avisos y mensajes informativos
• {{< button >}} para botones con diferentes variantes
• {{< pagelink >}} para enlaces presentados como tarjetas
• {{< columns >}} para crear contenido en varias columnas

Documentación

La documentación completa de Hudocs incluye instalación, configuración, estructura de contenido, shortcodes, traducciones, personalización y otras opciones avanzadas.

Puedes consultarla directamente en la demostración oficial: hudocs.com.

Conclusión

Hudocs nació como una herramienta para facilitar la documentación de mis propios proyectos y posteriormente decidí compartirla para que otras personas pudieran aprovecharla también.

Su objetivo es ofrecer una base sencilla y rápida para crear documentación con Hugo, manteniendo una estructura fácil de entender y evitando dependencias y herramientas adicionales innecesarias.

Si tienes alguna sugerencia, encuentras algún problema o quieres contribuir al proyecto, puedes hacerlo desde el repositorio en GitHub.