now I understood what you was saying, totally agree!
henriquesati
D4no0
Care to show examples of the said documentation from other languages that in your opinion is better than elixir? Just claiming that other languages have better documentation without arguments is not very constructive.
For example rust is a great example, for example tokio library. Great documentation and examples, even though I would say this doesn’t differ much from the documentation style of elixir libraries.
0
bartblast
Creator of Hologram
Thanks guys @christhekeele, @Eiji excellent feedback!
I added “Putting It All Together” section at the end of the page.
I also moved the section about chaining another actions to the bottom, because this is going to be a rare case.
I moved the section mentioned by @Eiji to the top of the “Actions Results” section and redacted it a little bit to explain that the functions called are pure and the whole process is composable.
The changes are live: https://hologram.page/docs/actions
2
christhekeele
Lovely, I think that works great as a capstone to the learning presented in the rest of the guide!
1
henriquesati
not muich singular cases, i’m refering about day to day use, I feel like more high level languages has a more noob friendly documentation, while elixir requests more from the user, try to check the most initial guide from libs like Numpy and compare to what you usually see in elixir
0
bartblast
Creator of Hologram
While building a custom website is significantly more time-consuming than using HexDocs, I believe it offers several key benefits:
- Custom syntax highlighting: especially important for our
.holotemplate syntax, which needs special treatment - AI-powered search: I’m planning to implement an AI agent that will not only provide better documentation search but also engage in conversational explanations of the docs
- Enhanced navigation: taking inspiration from Tailwind’s docs, I will implement a fixed right sidebar showing the current page’s contents. Check out how they do it here: https://tailwindcss.com/docs/adding-custom-styles
- Consistent branding: keeping everything aligned with Hologram’s visual identity
- Future extensibility: room for interactive examples, playgrounds, and other custom features
2
Eiji
You can do that! Simply create a package named like makeup_holo and use makeup API to register your lexel, see application.ex | MakeupEEx 1.0.0 @ GitHub.
Fine, but you can use hex to store documentation and create a standalone AI chat bot for it, right?
Ok, the sidebar is always on left, but there is no problem with navigation at all. Simply use heading tags in markdown like ## Examples. If you have some ideas to enhance navigation then you can propose changes to ex_doc.
Since across many versions there are different assets and they do not change (in specific old version) when hex is updated you should be able to override the assets. In doc/dist you can find CSS, JavaScript and even fonts, so it should be not a problem as long as you don’t want to change DOM and I guess that you could also change JavaScript to support your AI as well.
You can open documentation in LiveBook. If remember correctly you can even create custom cells. As far as I know it’s even possible to start Phoenix server from LiveBook, so if that’s not enough for you then I have no idea what you need.
3
Eiji
Oh, I forgot to mention that there are some options that you may find interesting … Please take a look at Extensions @ ex_doc documentation section to see how you can inject custom CSS and JavaScript, so you don’t even have to touch generated doc directory.
1
bartblast
Creator of Hologram
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.
3
bartblast
Creator of Hologram
The Commands documentation page is now available at https://hologram.page/docs/commands.
It complements the existing Actions page and covers server-side operations in Hologram 
3