Thanks all. I will start a KIP. Regards, Harish
On Wed, Jan 15, 2025 at 8:00 AM Divij Vaidya <divijvaidy...@gmail.com> wrote: > FYI there is also some prior attempts for converting to markdown at > https://issues.apache.org/jira/browse/KAFKA-14815 > > Please feel free to take over that Jira and start a KIP. > > -- > Divij Vaidya > > > > On Wed, Jan 15, 2025 at 2:57 AM Luke Chen <show...@gmail.com> wrote: > > > 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 > > > > > >
