Harish, thanks for putting this together! I have been wanting something like this for Kafka for a long time and I'm thrilled to see this come from the community.
I did some research on this a few months ago and found that Hugo and Docsy are somewhat common among ASF projects. Here are some real world examples I found: * https://parquet.apache.org (Docsy theme) * https://avro.apache.org (Docsy theme) * https://hadoop.apache.org * https://flink.apache.org * https://nifi.apache.org I am very supportive of this initiative. -David A On Tue, Jan 14, 2025 at 1:46 AM Swikar Patel <swikar....@gmail.com> wrote: > Yes prototype looks great! This is much better. > > Thanks > Swikar > > > On Jan 13, 2025, at 8:29 PM, Swikar Patel <swikar....@gmail.com> wrote: > > > > 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 > > > -- David Arthur
