Hi Harish, It seems great idea. Can you create Jira ticket?
Thanks, Swikar > On Jan 13, 2025, at 8:12 PM, Swikar Patel <swikar....@gmail.com> wrote: > > Are you creating KIP for this proposal? > > Thanks > Swikar > >> On Jan 13, 2025, at 7:58 PM, Harish Vishwanath <harish.shas...@gmail.com> >> wrote: >> >> 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
