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.

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.138.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

He incluido un archivo de configuración para Netlify que puedes usar de ejemplo. Copia el archivo demo/netlify.toml a la raiz de tu proyecto y por último crea un nuevo sitio en Netlify y conectarlo con tu repositorio de GitHub.

Vercel

También he agregado un archivo de configuración para Vercel que puedes usar de ejemplo. Copia el archivo demo/vercel.json, luego crea un proyecto en Vercel 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.