While we were designing future native parsers, nobody canceled the task of migrating to Flude at work. And that had its own corporate challenges.
The business had one ironclad condition: the migration to Flude had to be absolutely transparent. Our output (still running on Doxygen at the time) had to match the output of the old documentation generator one-to-one, both in completeness and in page structure, including the exact names of the generated HTML files.
A Different Philosophy of Structure
The problem lay in the fundamental difference in renderer philosophies. The modern approach to documentation generation implies that an entire class (with all its properties and methods) is rendered on a single, continuous page. Navigation within the class happens via standard HTML anchors (e.g., class.html#MethodName).
The old generator worked completely differently: for every single method, property, and class member, it created its own tiny, separate HTML page.
If we had applied the modern approach, we would have instantly broken a ton of old links, bookmarks, and internal integrations that the company's engineers had grown accustomed to over the years. We had to emulate this legacy structure at all costs.
Declarative sidebar.toml
For the company's specific needs, we had a dedicated private plugin. But I categorically did not want to hardcode the "page splitting" logic even there. The initial plan was: move the logic into flexible settings, and if it works well—transfer the feature to the main core.
The solution was a configuration file: sidebar.toml. It allowed us to manually configure the rules for forming the navigation menu and flexibly control how the logical structure of the code would map onto the physical file system and the structure of the documentation itself. This manifest allowed us not to hardcode the output, but to keep it entirely in the configuration.
Moving to the Main Core
The experiment turned out to be incredibly successful. Untying the physical output structure from the parser's internal architecture is a very powerful pattern.
As planned, we moved the sidebar.toml mechanics from the working plugin into the main Flude core, making it the absolute standard for generating any projects.
SaaS Limitations
True, there is one nuance. Even though the core now supports generating any custom structure via sidebar.toml, we do not yet give users this freedom in our cloud SaaS version.
Our cloud workers use a static sidebar.toml file that we place on the server ourselves. The user simply has no access to it and cannot pass their config from the outside. In the current SaaS version, the ability to change the structural configuration is locked. But the main thing is that the architectural foundation for it is already reliably laid in the core.
Conclusion
With the help of configuration, we successfully untied the output structure from the parser structure and completely satisfied the work requirements for links.
But to successfully deliver the project, one more visual problem remained. The old generator knew how to draw class inheritance diagrams in PNG format, and we needed to replicate this functionality. How we implemented image generation and why this feature also moved to the core—read about it in the next episode.
Originally published on our blog: https://blog.flude.guide/blog/sidebar-toml-legacy-routing
Also read us:
Top comments (0)