Como Criar Documentação Limpa Sem Gigabytes de node_modules
Quando você inicia um novo projeto ou mantém uma biblioteca em uma equipe, a questão da documentação básica inevitavelmente surge. Digamos que você não precisa de um portal monstruoso com roteamento dinâmico, componentes reativos e centenas de megabytes de dependências. Você só quer escrever alguns arquivos Markdown, apertar um botão e obter um site limpo com navegação em árvore, busca e adaptação mobile.
Docusaurus ou VuePress são escolhas comuns nessas situações. São boas opções, mas exigem toda uma maré de pacotes npm. Se você quiser evitar Node.js no seu pipeline de build e valorizar uma geração ultrarrápida, vale a pena dar uma olhada no tema Hugo Book de Alexander Shpak.
O que é este tema e para quem é
Hugo Book é um template minimalista para o gerador de sites estáticos Hugo, estilizado como um livro comum com menu lateral. O autor do projeto, Alexander Shpak, tinha um objetivo claro: criar um tema de design limpo que funcione rápido e não force os usuários a passar horas fuçando em arquivos de configuração.
O repositório acumulou mais de 4.000 estrelas no GitHub, o que é bem respeitável para um tema especializado do Hugo. O template reconhece o Markdown padrão e automaticamente constrói uma estrutura em árvore de páginas baseada no aninhamento de pastas.
Principais recursos por baixo do capô
Ao contrário de muitas ferramentas web modernas, Hugo Book segue uma dieta rigorosa. A funcionalidade principal do site funciona inteiramente sem JavaScript. A alternância do menu mobile, a expansão de seções aninhadas e a navegação em árvore são todas feitas em CSS puro.
Os recursos práticos incluem:
- Tema escuro integrado. Ele se adapta automaticamente às configurações do sistema operacional, mas você também pode adicionar uma alternância manual.
- Suporte multilíngue pronto para uso. O Hugo pode gerenciar estruturas de pastas paralelas para diferentes idiomas, e o tema renderiza corretamente um alternador de versão.
- Shortcodes integrados convenientes. Para estilizar notas, avisos, botões bonitos e abas de código, você não precisa inventar suas próprias gambiarras.
- Busca e comentários integrados. A busca pode ser implementada via um script leve integrado (FlexSearch) ou serviços de terceiros.
O princípio da intervenção mínima
O autor observa especificamente na filosofia do projeto: o tema não deve interferir nos layouts dos usuários ou sobrecarregar a configuração. Para lançar um site, você literalmente não precisa definir nenhum parâmetro específico em config.toml ou hugo.toml. O template reconhece a estrutura de conteúdo padrão do Hugo.
Se você precisar de estilos personalizados, pode sobrescrever CSS em algumas linhas através de um arquivo de extensão especial, sem tocar no código-fonte do tema. Isso evita dores de cabeça de manutenção quando o tema for atualizado em alguns meses.
Início rápido
Você vai precisar da versão estendida do Hugo (Hugo extended) versão 0.158 ou superior instalada. O processo de configuração leva dois minutos.
O caminho mais simples é usar o repositório starter pronto para uso:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Após iniciar o servidor local em http://localhost:1313, um site de documentação pronto será aberto. Quando você modificar arquivos Markdown, o Hugo atualiza a página no navegador quase instantaneamente. O tempo de build para sites com algumas centenas de páginas geralmente não excede uma fração de segundo.
Shortcodes para layout de texto
O Markdown padrão pode ser muito limitado quando você precisa destacar uma nota importante ou criar colunas. Hugo Book tem um conjunto de shortcodes integrados.
Por exemplo, o shortcode hint é usado para blocos de informação elegantes:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
E se você precisar mostrar exemplos de código para diferentes sistemas operacionais ou linguagens de programação, o shortcode tabs é útil:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Abordagem de versionamento
O tema é distribuído sob a licença MIT. O autor usa versionamento incremental (ex.: v0.13.0, v0.14.0). Mudanças incompatíveis entre lançamentos acontecem ocasionalmente, então para produção é melhor fixar em uma tag específica em vez de ficar no branch main.
Onde isso é útil
O tema é uma ótima escolha para:
- Documentação técnica de bibliotecas open source
- Base de conhecimento interna de equipe ou Wiki corporativa
- Instruções de deploy de serviços e APIs
- Blog de engenharia pessoal ou coleção de anotações
Se você precisar de interatividade pesada, gráficos 3D diretamente na documentação ou integração profunda com componentes React, o Hugo Book provavelmente não vai servir. Nesse caso, você precisaria olhar para Docusaurus ou Astro Starlight. Mas para tarefas típicas de documentação, a simplicidade do Hugo Book é mais do que suficiente.
Pecados ocultos
Com todas as vantagens, você precisa entender as nuances da infraestrutura do Hugo. O motor de templates Go HTML Templates que sustenta o Hugo tem uma sintaxe específica. Se você quiser reescrever radicalmente a estrutura do cabeçalho ou rodapé, precisará investir tempo aprendendo a estrutura de templates do Go.
Além disso, o índice de busca para busca local é gerado no momento do build. Para sites enormes com dezenas de milhares de páginas, o arquivo de busca pode ficar pesado, embora para guias típicos isso não seja problema nenhum.
Em resumo
Hugo Book é uma ferramenta honesta sem brilho desnecessário. Ele faz exatamente o que promete: transforma um punhado de pastas com Markdown em um site rápido, limpo e legível. Sem pacotes npm para instalar, sem builds demorados e sem configuração complexa.
Projetos relacionados