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 > > >
