ADR-006: Hugo for Technical Documentation
Status: Accepted
Date: 2025-09-05
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski
Hugo with Geekdoc theme is adopted for technical documentation to provide fast, maintainable, and developer-friendly documentation platform. This enables markdown-first content creation with excellent performance and built-in navigation features.
# Install Hugo (binary or package manager)
wget https://github.com/gohugoio/hugo/releases/download/v0.115.0/hugo_extended_0.115.0_Linux-64bit.tar.gz
# Create new site
hugo new site documentation-site
# Development server with live reload
hugo server -D --bind 0.0.0.0 --port 1313
# Production build
hugo --minify --cleanDestinationDir
# Add new content page
hugo new content/section/page-name.md
- Navigation: Configure in
config.yamlwithgeekdocNav: true - Search: Built-in search with no additional setup required
- Theming: Dark/light mode toggle included
- Mobile responsive: Automatic mobile optimization
- Content organization: File-based structure with front matter
The Entirius project requires a robust technical documentation platform to support developers, users, and contributors. The documentation needs to be:
- Easy to maintain and update by technical team members
- Support markdown format for developer-friendly content creation
- Generate static sites for fast loading and good SEO
- Support navigation structure and search functionality
- Integrate well with our existing development workflow
- Be cost-effective to host and maintain
The documentation includes Architecture Decision Records (ADRs), development guides, API documentation, and user guides that need to be accessible and well-organized.
- Description: React-based static site generator specifically designed for documentation
- Pros:
- Excellent developer experience with React ecosystem
- Built-in search and navigation features
- Good integration with OpenAPI specs
- Strong community and Facebook backing
- Cons:
- Requires Node.js knowledge for customization
- More complex setup than simpler alternatives
- Heavier runtime compared to pure static generators
- Impact on system: Would require Node.js tooling in documentation workflow
- Description: Go-based static site generator with documentation-focused theme
- Pros:
- Extremely fast build times (written in Go)
- Simple markdown-first approach
- Geekdoc theme specifically designed for technical documentation
- Built-in search functionality
- Easy navigation configuration
- Minimal dependencies and lightweight
- Cons:
- Less ecosystem compared to React-based solutions
- Theme customization requires Hugo templating knowledge
- Fewer plugins compared to other platforms
- Impact on system: Single binary dependency, very fast builds
- Description: Commercial documentation platform with Git integration
- Pros:
- Professional appearance and user experience
- Built-in collaboration features
- Good integration with Git workflows
- Cons:
- Commercial service with ongoing costs
- Less control over hosting and customization
- Vendor lock-in concerns
- Impact on system: External dependency with recurring costs
Chosen option: Hugo with Geekdoc Theme
Key decision factors:
- Performance: Hugo’s Go-based architecture provides extremely fast build times (sub-second for incremental changes), crucial for large documentation sites
- Developer Experience: Markdown-first approach aligns perfectly with technical team’s existing workflow and version control practices
- Cost Effectiveness: No licensing costs and can be hosted on any static hosting platform, supporting long-term sustainability
- Maintenance: Single binary dependency reduces complexity in build pipeline and eliminates Node.js/npm dependencies
- Risk analysis: Low technical risk with mature, stable platform and simple deployment requirements
- Business impact: Fast iteration on documentation supports better developer onboarding and community engagement
- Compatibility: Integrates well with existing Git workflows and can be hosted alongside other static assets