Hi all, Back in April, I started a discussion with KIP-1133: AK Documentation and Website in Markdown. (Link: https://cwiki.apache.org/confluence/display/KAFKA/KIP-1133%3A+AK+Documentation+and+Website+in+Markdown). The KIP proposes migrating the Kafka website and its documentation from the current system (which uses raw HTML files) to a modern, Markdown-based system.
I'm happy to report that since the KIP was approved, significant progress has been made, and a version is now ready for community review. *Progress Highlights:* 1. *Staging Site:* A full version of the website, built from Markdown, is now live at: *https://kafka.staged.apache.org/ <https://kafka.staged.apache.org/>* 2. *Source Code:* The Markdown source is available on the markdown branch of the kafka-site repository: https://github.com/apache/kafka-site/tree/markdown 3. *CI/CD Pipeline:* A GitHub Actions pipeline is fully configured. ( https://github.com/apache/kafka-site/actions) - It automatically builds and deploys commits/PRs from the markdown branch to the staging site. - It also builds a Docker image for easy local preview. You can run it locally with: docker run -p 8080:80 ghcr.io/apache/kafka-site:markdown 4. *Conversion Tooling:* An automation pipeline was developed to perform the HTML-to-Markdown conversion, which can be found here: https://github.com/hvishwanath/ak2md 5. *Local Development:* Makefiles are included to ease local development and iteration. 6. *Developer README:* Comprehensive instructions on how to build the site and make updates are available in the README: https://github.com/apache/kafka-site/blob/markdown/README.md *Call for Review (Now - Nov 30):* I would like to formally invite the community to review the staging site and the Markdown source code. - *What to look for:* Please compare the staging site ( https://kafka.staged.apache.org/) with the live site ( https://kafka.apache.org/) and look for any rendering issues, broken links, content discrepancies, or formatting errors. - *How to fix:* If you find any issues, please feel free to submit a PR directly against the markdown branch. This is a great opportunity to fix any small typos or formatting issues you may have seen in the docs. This has been a huge undertaking, and you will likely spot minor issues like broken links or rendering quirks. Many of these stem from inconsistencies in the original HTML source, which I have done my best to detect and fix via automation. I strongly encourage the community to view these as non-gating issues that can be easily fixed post-migration, rather than blockers for the cut-over itself. *Proposed Cut-over Plan:* To move this forward, I propose the following plan: 1. *Now – Nov 30: Community Review Period* - The community reviews the staging site and source code. - Fixes are submitted as PRs directly to the markdown branch. 2. *Dec 1: Final Sync* - I will perform one final refresh from the main repository to pull in any last-minute documentation changes from the HTML source. 3. *First Week of Dec: Start [VOTE] Thread* - I will start a formal vote thread to ask the community to approve the cut-over to the new Markdown-based site. 4. *If the Vote Passes:* - We will migrate the source documentation in the docs directory of the apache/kafka repository to Markdown for versions *3.5 and newer*. - Older versions (pre-3.5) will be left as-is (HTML) in the kafka repo to avoid disruption. - The GitHub Actions will be updated to deploy the markdown branch to the live production site. - A key benefit of this change: any future bug fixes needed for *older* (pre-3.5) documentation can be made directly in the kafka-site repository, decoupling them from the main Kafka release process. Finally, I want to extend a huge and sincere thank you to *David Arthur*. His guidance, detailed code reviews, help in refactoring the CI pipeline, and merging PRs over the last several months have been invaluable in getting this KIP to its current state. Please take a look at the staging site and let me know your thoughts. Regards, Harish
