Hi Harish, Thanks for the proposal. Sounds good to me. But please write a formal KIP <https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals> for this idea.
Thanks. Luke On Tue, Jan 14, 2025 at 10:22 PM David Arthur <mum...@gmail.com> wrote: > 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 >
