Hello AK Community, I am writing to propose an improvement to the Apache Kafka website/documentation infrastructure . I noticed that with the current documentation <https://github.com/apache/kafka-site> we store raw HTML in version control, making it challenging to maintain, update and test effectively. I believe transitioning to a markdown based source can be beneficial to the community.
I propose migrating the Apache Kafka website and documentation to Markdown files, managed through Hugo <https://gohugo.io/documentation/> —a modern static site generator and leverage richer themes such as the Docsy <https://www.docsy.dev/docs/get-started/> theme, which is widely used by other projects such as Kubernetes <https://github.com/kubernetes/website> and Istio <https://github.com/istio/istio.io>. This approach brings a few benefits: - Improved Maintainability - Markdown is simpler and more readable than raw HTML, making contributions easier for developers of all skill levels. Further, with Hugo’s built-in live preview feature, contributors can instantly see how their changes will render. - Leverage richer, modern features - Themes such as “Docsy” provide a clean, responsive design with built-in support for features like local search, support for internationalization etc., - We can also take this opportunity to refactor, rearrange and update our content to improve readability and maintainability - Improved Portability/Testability - Static sites generated by Hugo are server-agnostic, simplifying deployment. - Improves local testing as well as CI testing To demonstrate the feasibility of this transition, I created a working prototype of the Apache Kafka documentation using Hugo and Docsy. Please take a look. - Prototype : https://kafka-site-md-711970345036.us-central1.run.app/. - Source code for the website: https://github.com/hvishwanath/kafka-site-md . Specifically “content/en” directory shows the markdown source with some refactoring for improved maintainability. - I wrote some automation to help with this: https://github.com/hvishwanath/ak2md I would love to hear your thoughts on this proposal. Cheers Harish
