Documenta tus proyectos fácilmente con HuDocs

Documentar es tedioso pero muy importante para que otras personas puedan entender tu código, usarlo y colaborar en él.

Aprende a crear documentacion de tu proyecto con gohugo

Documentar es tedioso pero muy importante para que otras personas puedan entender tu código, usarlo y colaborar en él. Por eso he creado el tema HuDocs para facilitar esta tarea, permitiéndote documentar tu proyecto de forma sencilla y rápida escribiendo archivos Markdown y organizándolos en carpetas.

Características

HuDocs es un tema para Hugo que puedes usar libremente ya que está publicado bajo la licencia MIT. Algunas de sus características son:

Optimizado compatible con Core Web Vitals
Nivel de Seguridad A+ en Mozilla Observatory
Soporte para múltiples idiomas
Sin dependencias
Buscador avanzado automatizado
Tema claro y oscuro
Shortcodes para alertas, notas, tablas, etc.
Bloques de código avanzados
Alta personalización

Requisitos

Para usar HuDocs necesitas tener instalado Hugo en su versión extendida (extended) y Git en tu ordenador. En concreto necesitas:

Hugo 0.100.0 o superior (versión extendida)
Git - Instalar Git
Ganas de documentar

Instalación

Para instalar HuDocs, ve a la raíz de tu proyecto de Hugo y ejecuta el siguiente comando:

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

Estructura recomendada

Puedes usar cualquier distribución de archivos y carpetas, no esta limitado a una estructura en concreto, pero si tienes multiples versiones de un mismo proyecto, recomiendo que la primera carpeta de sección tenga el número de versión, por ejemplo:

content
└── 1.0
└── 1.1
    └── index.md

Para que puedas entender mejor el motivo de esta estructura, he dejado un ejemplo en la carpeta demo, para traerlo a la carpeta de contenido y poder verlo en tu servidor local, ejecuta el siguiente comando:

cp -R themes/docs/demo/content .

Configurar

El tema contiene algunas opciones útiles que te pueden ayudar a personalizar aún mas tus documentos. Copia el archivo demo/config.toml y reemplazar la información con tus datos. Por último inicia el servidor local ejecutando:

hugo serve

Personalizar

HuDocs es un tema muy personalizable, si deseas hacer cambios en el tema, te recomiendo que crees un archivo _custom.scss en la carpeta assets/scss/_custom.scss ubicado en la raíz de tu proyecto y agrega tus estilos personalizados allí.

Netlify

También he incluido un archivo de configuración para Netlify que puedes usar de ejemplo. Copia el archivo demo/netlify.toml y reemplazar la información con tus datos. Luego solo tienes que crear un nuevo sitio en Netlify y conectarlo con tu repositorio de GitHub.

Conclusión

HuDocs es un tema que he creado para facilitar la documentación de mis proyectos, pero que decidí compartir para ahorrarle tiempo a otras personas que también necesiten documentar sus proyectos. Si tienes alguna sugerencia o mejora, no dudes en compartirla conmigo.