We promised to cover the integration of Developer Guides in the previous article. We changed our approach to building these guides twice. We initially moved them completely outside the Flude generator. Harsh reality eventually forced us to reconsider that decision.
The first attempt: monolithic HTML generator
A single clunky tool built both the API reference and the guides on the old HTML stack. The guides covered standard scenarios like quick starts and custom project development. They also included collections of articles detailing SDK-specific features. These topics relate to working with the platform as a whole and require dedicated text descriptions.
We blindly carried this monolithic integration over into the first version of Flude. The old workflow seemed perfectly fine. The subject matter of the guides remained exactly the same, so nobody thought about decoupling the processes.
The second attempt: the illusion of plain Markdown
We decided to remove the guides from Flude's jurisdiction during the transition to a static site generator. The logic felt rock-solid. We wanted our parser to handle the complex API extraction. Handwritten guides are just standard Markdown text that the static generator can assemble on its own. The initial translation from HTML required minimal automation.
The guides moved into a separate directory—the SSG picked them up directly without any preprocessing. Flude dropped out of this build step entirely. The separation looked great on paper since two independent content sources only met on the final page.
Returning to a unified process
We eventually noticed a massive navigation problem. The guides knew absolutely nothing about the API reference pages. The reference had no idea the guides existed. Links to classes or methods led nowhere if the target page hadn't generated yet. They also died quietly when paths changed during a rebuild. Neither process could see the other to flag the broken connection.
We brought Developer Guides back under Flude's control using a different approach. The engine no longer renders them directly. It now validates the file formatting and tracks the integrity of cross-references. The SSG still handles the final portal assembly. Flude integrates into this pipeline as a dedicated validation step. Both systems operate within a unified workflow that catches broken links before publication.
Clean architectural separation often crashes against real-world requirements. Splitting systems apart inevitably requires building reliable bridges between them. The next article explores the Typed Models that helped us organize scattered data into a predictable structure.
Originally published on our blog: https://blog.flude.guide/blog/developer-guides-return
Also read us:
Top comments (0)