Thanks for the detailed feedback @Eiji! You make excellent points about ExDoc/HexDocs/Makeup extensibility. Let me explain why I still believe a custom website is the right choice for Hologram specifically:
Current State vs Future Vision
While what we have now on the Hologram website would fit into HexDocs, that’s just scratching the surface. After working on Hologram for almost 5 years and being committed to at least 5 more, I have a broader vision for what the documentation platform needs to become.
Dogfooding & Framework Showcase
The documentation site itself is built with Hologram, serving as a real-world example of the framework’s capabilities. This “dogfooding” approach helps validate the framework and provides a reference implementation that demonstrates best practices.
Framework-Specific Requirements
Hologram needs to control the whole browser to run its machinery - there’s complex transpilation, routing, and template handling underneath. This makes it challenging to use platforms like LiveBook for interactive examples.
Advanced Syntax Highlighting
While Makeup is excellent, our needs go beyond standard syntax highlighting. We’ll eventually implement Hologram macro components with access to the framework’s internal machinery for enhanced highlighting and language server capabilities.
Marketing & Brand Identity
As a frontend framework competing with LiveView, using LiveView-based tools like LiveBook for our documentation would be counterproductive from a marketing perspective. The custom website allows us to maintain consistent branding and showcase Hologram’s unique capabilities.
Future-Proofing & Risk Management
Given Hologram’s scope, we need flexibility for future features that might not fit within HexDocs/LiveBook constraints. The custom platform gives us complete control over:
- Interactive component playgrounds (similar to Storybook)
- Real-time demonstrations
- Community showcases (serving users’ demo apps within Hologram website)
- Product analytics for documentation usage
- AI-powered assistance that’s deeply integrated with framework internals
- …and other crazy ideas we haven’t even thought of yet!
Community Consideration
I want to emphasize that this isn’t about starting a movement away from HexDocs. ExDoc/HexDocs/Makeup are fantastic tools that serve 99% of Elixir projects perfectly. This decision is specific to Hologram’s unique position as a frontend framework with specialized documentation needs.
The goal isn’t to replicate HexDocs features, but to create documentation that’s specifically optimized for teaching and demonstrating Hologram’s capabilities, similar to how successful JS frameworks have custom documentation platforms that showcase their specific patterns and features. The documentation becomes not just a reference, but a kind of a learning platform that presents the framework concepts in an integrated way.
