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
