Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hello, I'm planning to initiate a vote on this KIP next week. In the meantime, please share any further questions or comments you may have. Regards, Harish On Tue, Mar 11, 2025 at 7:42 AM David Arthur wrote: > TaiJuWu, > > Hugo has a Docker image which makes it very easy to run locally, and I

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Thank you Chia-Ping. Conversion is mostly automated ( https://github.com/hvishwanath/ak2md ) and as such the prototype supports all previous versions. However, not having to support all previous versions will definitely be simpler. Hugo su

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

TaiJuWu, Hugo has a Docker image which makes it very easy to run locally, and I expect many developers have Docker installed already. I'm not totally sure, but I don't think this would require any build support (Gradle or Hugo/Go). I believe you would simply mount the docs directory in the docker

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hi Harish, Thanks for this KIP. Is it possible to add dev website from trunk for developers? It could help developer to browser the web without local build and check recent documentation change quickly. I think it can improve our documentation a lot since developers can easy to check it. Best, T

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Thanks Chia-Ping. I have updated the KIP to include the above information. Regards, Harish On Sun, Mar 9, 2025 at 10:09 PM Chia

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

hi Harish > Hugo supports live-reload. The docsy theme has dependencies on golang and a couple of nodeJS libraries (autoprefixer, postcss etc.,) and as such it will be simpler to use docker based workflows to avoid having to install any dependencies locally for development (ref: https://github.com

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

hi Harish I have to say, this KIP is one of the best ideas I've seen recently, and I agree with Matthias that we don't need to translate any older versions. I truly hope this KIP can be included in 4.0. I have a quick question: what is the recommended procedure for testing the site locally after

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hello all Sorry for my delayed response. Thanks for your feedback and comments. Please see below: > Do you plan to have a development version of the website online in parallel to the old HTML version? Yes. The current prototype which supports all versions until AK 3.9 is running at https://kafka-

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hi, I am totally in favor to make this happen, and I was disappointed each time in the past, when it was proposed but we did not do it. Given that it is a huge effort, I am wondering if it would be sufficient to just to this change for 4.0 release though, and not translate any older versio

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

MM1: I suspect Hugo has some way of doing url redirection, but at the very least we can add redirects in our htaccess file https://github.com/apache/kafka-site/blob/asf-site/.htaccess Excluding the "front matter" (intro, quickstart, powered by, etc) I think the main links we need to worry about ar

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

I have been working on a similar process for Apache RAT and Commons CLI (help module). The help option in RAT 0.17-SNAPSHOT generates the text for the help options partly from the new commons-cli help module and partly from Enums and similar in the code. For the RAT documentation we produce fragm

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hi Harish, This is definitively something we want to do! MM1. One aspect to keep in mind in terms of compatibility is whether existing links will still work. Thousands of online resources link to the Apache Kafka website. Is it possible to keep all links working? MM2. A bunch of sections are gen

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hi Harish, Thanks for the KIP! Great initiative! Do you plan to have a development version of the website online in parallel to the old HTML version? I understand that locally with the markdown files and an markdown editor, we see the rough structure of the docs (which is already an improve

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Thank you David. Appreciate your feedback. My comments below: DA1) I think this is a very good suggestion. While building the prototype, I did spend additional effort for older versions of the doc since there are fairly significant differences in the structure and format of the documents as compar

Re: [DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Thanks for the KIP, Harish! I am +100 just on the title alone :) The motivations in the KIP are sound. All of these are very real annoyances when it comes to maintaining our docs. I suspect we have not done anything to improve them since the system we have worked well enough in the past. A better

[DISCUSS] KIP-1133: AK Documentation and Website in Markdown

Hello, Following up from my previous email regarding moving AK documentation to markdown, I wrote KIP-1133 detailing the proposal and would like to start discussions. Please take a look. Regar