Cómo crear documentación limpia sin gigabytes de node_modules
Cuando inicias un nuevo proyecto o mantienes una biblioteca en un equipo, inevitablemente surge la cuestión de la documentación básica. Digamos que no necesitas un portal monstruoso con enrutamiento dinámico, componentes reactivos y cientos de megabytes de dependencias. Solo quieres escribir unos pocos archivos Markdown, presionar un botón y obtener un sitio limpio con navegación en árbol, búsqueda y adaptación móvil.
Docusaurus o VuePress son opciones comunes en estas situaciones. Son buenas opciones, pero arrastran consigo todo un mar de paquetes npm. Si quieres evitar Node.js en tu pipeline de compilación y valoras la generación ultrarrápida, vale la pena echarle un vistazo al tema Hugo Book de Alexander Shpak.
Qué es este tema y para quién es
Hugo Book es una plantilla minimalista para el generador de sitios estáticos Hugo, estilizada como un libro común con un menú lateral. El autor del proyecto, Alexander Shpak, tenía un objetivo claro: crear un tema de diseño limpio que funcione rápido y no obligue a los usuarios a enterrarse en archivos de configuración.
El repositorio ha acumulado más de 4.000 estrellas en GitHub, lo cual es bastante respetable para un tema especializado de Hugo. La plantilla reconoce el Markdown estándar y construye automáticamente una estructura en árbol de páginas basada en el anidamiento de carpetas.
Características principales bajo el capó
A diferencia de muchas herramientas web modernas, Hugo Book sigue una dieta estricta. La funcionalidad principal del sitio funciona completamente sin JavaScript. Alternar el menú móvil, expandir secciones anidadas y la navegación en árbol se hacen todo en CSS puro.
Las características prácticas incluyen:
- Tema oscuro integrado. Se adapta automáticamente a la configuración del sistema operativo, pero también puedes agregar un interruptor manual.
- Soporte multilingüe de fábrica. Hugo puede gestionar estructuras de carpetas paralelas para diferentes idiomas, y el tema renderiza correctamente un selector de versiones.
- Shortcodes integrados convenientes. Para dar estilo a notas, advertencias, botones elegantes y pestañas de código, no necesitas inventar tus propios trucos.
- Búsqueda y comentarios integrados. La búsqueda se puede implementar mediante un script ligero integrado (FlexSearch) o servicios de terceros.
El principio de intervención mínima
El autor específicamente señala en la filosofía del proyecto: el tema no debe interferir con los diseños de los usuarios ni sobrecargar la configuración. Para lanzar un sitio, literalmente no necesitas configurar ningún parámetro específico en config.toml o hugo.toml. La plantilla toma la estructura de contenido estándar de Hugo.
Si necesitas estilos personalizados, puedes sobrescribir CSS en un par de líneas a través de un archivo de extensión especial, sin tocar el código fuente del tema. Esto te ahorra dolores de cabeza de mantenimiento cuando el tema se actualice en unos meses.
Inicio rápido
Necesitarás la versión extendida de Hugo (Hugo extended) versión 0.158 o superior instalada. El proceso de configuración toma dos minutos.
El camino más simple es usar el repositorio inicial listo para usar:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Después de iniciar el servidor local en http://localhost:13
Shortcodes para diseño de texto
El Markdown estándar puede ser demasiado limitado cuando necesitas resaltar una nota importante o crear columnas. Hugo Book tiene un conjunto de shortcodes integrados.
Por ejemplo, el shortcode hint se usa para bloques de información elegantes:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
Y si necesitas mostrar ejemplos de código para diferentes sistemas operativos o lenguajes de programación, el shortcode tabs resulta útil:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Enfoque de versionado
El tema se distribuye bajo la licencia MIT. El autor usa versionado incremental (por ejemplo, v0.13.0, v0.14.0). Ocasionalmente sí hay cambios importantes entre versiones, por lo que para producción es mejor fijar a una etiqueta específica en lugar de quedarse en la rama principal.
Dónde resulta útil
El tema es una excelente opción para:
- Documentación técnica de bibliotecas de código abierto
- Base de conocimientos interna del equipo o Wiki corporativa
- Instrucciones de despliegue de servicios y API
- Blog personal de ingeniería o colección de notas
Si necesitas interactividad pesada, gráficos 3D directamente en la documentación, o integración profunda con componentes React, Hugo Book probablemente no sea la mejor opción. En ese caso, tendrías que mirar hacia Docusaurus o Astro Starlight. Pero para tareas típicas de documentación, la simplicidad de Hugo Book es más que suficiente.
Trampas y dificultades
Con todas las ventajas, necesitas entender los matices de la infraestructura de Hugo. El motor de plantillas Go HTML Templates que sustenta a Hugo tiene una sintaxis específica. Si quieres reescribir radicalmente la estructura del encabezado o pie de página, tendrás que invertir tiempo en aprender la estructura de plantillas Go.
Además, el índice de búsqueda para la búsqueda local se genera en tiempo de compilación. Para sitios enormes con decenas de miles de páginas, el archivo de búsqueda puede volverse pesado, aunque para guías típicas esto no es un problema en absoluto.
En resumen
Hugo Book es una herramienta honesta sin brillo innecesario. Hace exactamente lo que promete: convierte un montón de carpetas con Markdown en un sitio rápido, limpio y legible. Sin paquetes npm que instalar, sin compilaciones largas y sin configuración compleja.
Proyectos relacionados