Thanks for the feedback Murali! I'm glad to hear the home page is looking great.
Regarding the missing sub-menus and navigation structure, I'd like to clarify the design approach taken with the new Hugo-based site, which aligns with what is documented in the KIP-1133 ( https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=340036497#KIP1133:AKDocumentationandWebsiteinMarkdown-AKversionspecificdocumentation ) 1. Content Organization & Navigation: Unlike the original website, the new source is organized into modular sections. Large, monolithic pages (like `ops.html` or `configuration.html`) have been split into smaller, more manageable pages. - Left Sidebar:Automatically displays these sections and pages as the primary navigation menu. - Right Sidebar (TOC): Displays the headings (H2, H3, etc.) within the current page. 2. Why not merge TOC into the Left Sidebar? I explored integrating the TOC headings directly into the left sidebar menu to mimic the previous "sub-menu" feel. However, this resulted in an excessively deep hierarchy that became cluttered and difficult to navigate. It also proved technically challenging to apply selectively to only certain sections without complicating the build logic. Instead of a deep nested menu, I've implemented a hybrid navigation (with left sidebar and right toc navbar) system to make finding content easier: Further, I added the following enhancements: - Sticky & Seamless Scrolling: Both the Left Sidebar and Right TOC are now sticky. They scroll seamlessly with the main content but can also be scrolled independently. - Smart Scrollspy: Right TOC automatically highlights the current location. If the user is viewing a deep subheading (e.g., H4) that isn't in the TOC, it intelligently highlights the parent section so that context is preserved= . - Offline Search: fast, local search (using Lunr.js) that indexes the latest documentation. This makes finding specific details instantaneous, often faster than navigating a complex menu. - Powered By Page: I have updated the "Powered By" page to match the spacing, width, and order of the cards as you suggested. Here is a gif showing this in action: https://gist.github.com/hvishwanath/461fd54c792b84fd23bbc952560b9235 The latest changes are live at https://kafka.staged.apache.org/. I believe this combination of structured page navigation, context-aware TOC, and fast search provides strong support for navigation and offers a good user experience. Thanks again for all your review, feedback and suggestions. Looking forward to starting the vote thread soon. Regards, Harish On Wed, Nov 26, 2025 at 3:09 AM Muralidhar Basani via dev < [email protected]> wrote: > Nice work Harish. > The home page is looking great. > > A few final bits. > Sub menus are missing > > APIs > > Producer API > Consumer API > Share Consumer API (Preview) > Streams API > Connect API > Admin API > > > Configurations > > Sub menus for > Configuration providers > Kafka connect configs > > > Design > > Motivation > Persistence > Efficiency > The Producer > The Consumer > Message Delivery Semantics > Using Transactions > Share Groups > Replication > Log Compaction > Quotas > > > Operations > Operations includes several menus and submenus. This gives a clear view > and makes them easily accessible. > > Kafka Connect > Submenus are missing under User Guide and Connect Development Guide. > > Can we align the "Powered by" page similarly to the existing page, matching > the spacing and page width? > > With these changes, I believe we will be ready for the cut-over. We have a > few minor improvements, but those can wait. > > Thanks, > Murali > > On Tue, Nov 25, 2025 at 4:09 PM Harish Vishwanath < > [email protected]> > wrote: > > > Thank you Murali for the detailed feedback. I have addressed all your > > comments and the site is live at https://kafka.staged.apache.org/ > > > > Regards, > > Harish > > > > > > On Sat, Nov 15, 2025 at 12:19 AM Muralidhar Basani > > <[email protected]> wrote: > > > > > Great work Harish. > > > > > > We are getting there. > > > > > > A few more items for the home page: > > > > > > 1. Not sure why we changed the menu item from 'Powered by' to > > > 'Testimonials'? If this was agreed upon in kip or any PRs, it's fine. > > > Otherwise, we should stick to the 'Powered by' menu item. > > > > > > 2. Instead of big search text box, replace it with a magnifying glass > > icon. > > > On click, it should display a text box underneath. > > > > > > 3. With the above change (point 2), we can wrap the 'DOWNLOAD' menu as > a > > > gradient button. > > > > > > 4. Better we keep the same menu items > > > > > > Get Started > > > Docs > > > Powered By > > > Community > > > Releases (added) > > > Apache > > > > > > and Download as the last menu item. > > > > > > And move the 'Blog' menu under 'Community'. > > > I think we don't need too many menu items. > > > > > > 6. Reduce the font size of menu items by 2 or 3 px. > > > > > > 7. Text color 'See full list' should be same as text color of 'Learn > > More' > > > > > > 8. The size of logo in the nav bar is a bit small. Can we increase its > > size > > > and move it closer to the menu items? Please see the current page. > > > > > > 9. Can we reduce the font size of text on cards like 'High Throughput' > > and > > > 'Deliver messages at net....' and on all cards and rows below them? > > > > > > 10. Pls reduce the height of the footer and ensure it has a fair > > > background. (optional) > > > > > > 11. Footer text hyperlinks have a blue color. Pls keep the full text in > > the > > > same color. Pls see the existing documentation. > > > > > > Please compare the current home page with the existing home page. > Several > > > minute details matter. It would have been easier if we had a Figma > > design. > > > I can also help you with PR reviews, if you prefer it that way. > > > > > > Let me know what is comfortable. > > > > > > Thanks, > > > Murali > > > > > > > > > On Thu, Nov 13, 2025 at 3:51 PM Harish Vishwanath < > > > [email protected]> > > > wrote: > > > > > > > Hello Murali, thanks again for your detailed review and comments. > > > > > > > > I have addressed all of them in the latest update and it is live at > > > > https://kafka.staged.apache.org/ < > https://kafka.staged.apache.org/%29 > > >. > > > > > > > > > > > > Regards, > > > > Harish > > > > > > > > > > > > On Tue, Nov 11, 2025 at 12:38 PM Muralidhar Basani > > > > <[email protected]> wrote: > > > > > > > > > Hi Harish, > > > > > > > > > > Thanks, I see improvements. > > > > > > > > > > I have a few more comments below only for home page : > > > > > > > > > > 1. Menu is still not responsive. I was expecting a burger icon in > > > mobile > > > > > mode. > > > > > 2. Menu 'Releases' is missing in mobile mode > > > > > 3. Font selection and sizes of menu is not matching > > > > > 4. Is it possible to display any drop down menu just on hover of > menu > > > > items > > > > > ? > > > > > 5. Is it possible to have any sub menu items. For ex : Under DOCS > - > > > > > > 6. Why did we change menu 'DOCS' to 'Documentation' ? I don't know > > what > > > > was > > > > > agreed though. > > > > > 7. Missing 'Apache' menu here, which I think it's there for a > reason. > > > > > 8. Logo on the top teft in home page - 'Apache Kafka' is probably > is > > in > > > > > white color making it hidden. We only see half the logo, not text. > > > > > 9. For transportation 8 out of 10 icon, there seems to be another > > > 'right > > > > or > > > > > tick' symbol on top of flight. > > > > > 10. We see 6 of these cards like 'Manufacturing 10 out of 10' etc, > > but > > > > > missing 'See full list' which should redirect to Testimonials ? > > > > > 11. Can we make these 6 use case cards get closer and shrink in > size > > > > > similar to existing docs may be ? It would look better. > > > > > 12. There are various font types used in existing docs in home page > > > which > > > > > make it more professional which am missing in the staging. > > > > > 13. There is a huge unexpected gap between text and images > > > > > (Manufacturing...) > > > > > 14. Text is missing 'Above is a snapshot of the number of top-ten > > > largest > > > > > companies using Kafka, per-industry.' > > > > > 15. We are missing the full footer here 'The contents of this > website > > > > are © > > > > > 2025 Apache Software Foundation under the terms of the Apache > License > > > v2. > > > > > Apache Kafka, Kafka, and the Kafka logo are either registered > > > trademarks > > > > or > > > > > trademarks of The Apache Software Foundation in the United States > and > > > > other > > > > > countries.Security | Donate | Thanks | Events | License | Privacy' > > > > > 16. Missing ASF leaf icon at the bottom right > > > > > 17. Can we use the same font style here for text 'Apache Kafka is > an > > > > > open-source distributed....' > > > > > 18. Is there a way to highlight 'Download Kafka' which am missing > > here. > > > > It > > > > > has a great look there in existing docs. > > > > > 19. For ex let's consider this text: Mission Critical > > > > > Support mission-critical use cases with guaranteed ordering, zero > > > message > > > > > loss, and efficient exactly-once processing. > > > > > Has different font settings. > > > > > 20. 3 Cards in a row like 'High throughput' could have some side > > space > > > on > > > > > both sides of the page. This is not aligned with content above. > > > Consider > > > > > some free space to get an elegant look. > > > > > > > > > > I am being too picky about this homepage, but I'm trying to give > it a > > > > look > > > > > similar to our existing pages without deviating too much. > > > > > > > > > > So far great work in getting the content there but let's focus on > > text, > > > > > font colors, sizes, etc to make it much more professional. > > > > > > > > > > Will look at the other pages soon. > > > > > > > > > > Thanks, > > > > > Murali > > > > > > > > > > On Tue, Nov 11, 2025 at 4:45 PM Harish Vishwanath < > > > > > [email protected]> > > > > > wrote: > > > > > > > > > > > Hi Murali, > > > > > > > > > > > > Thank you very much for taking the time to provide such detailed > > and > > > > > > valuable feedback on the staging site.I was able to address all > the > > > > > issues > > > > > > you raised. > > > > > > > > > > > > The latest version of the staging site, available at [ > > > > > > > > https://kafka.staged.apache.org/](https://kafka.staged.apache.org/), > > > > > > reflects these fixes. Please take a moment to review the updated > > site > > > > at > > > > > > your convenience. > > > > > > > > > > > > Here is a summary of the issues you pointed out and the > > corresponding > > > > > > updates: > > > > > > > > > > > > - **Responsiveness:** The staging link is now fully responsive, > > > > > addressing > > > > > > layout issues with the menu and logo on various devices. > > > > > > > > > > > > - **Favicon and Title:** The favicon and page titles are now > > properly > > > > > set. > > > > > > > > > > > > - **Homepage Cards:** > > > > > > > > > > > > - The repeated "Manufacturing" block on the home page has been > > > removed. > > > > > > > > > > > > - The display of the 'Core capabilities' and 'Ecosystem' cards > has > > > been > > > > > > adjusted to ensure they are visually distinct and include proper > > > > headers. > > > > > > > > > > > > - **Interactive Elements (Streams API):** Implemented an > > interactive > > > > > > carousel. > > > > > > > > > > > > - **- Code Snippets:** The selection for Java/Scala in code > > snippets > > > > is > > > > > > now functional. > > > > > > > > > > > > - **- Testimonials Alignment:** The Testimonials section, > > including > > > > use > > > > > > cases like Zalando and Rabobank, has been realigned, and the card > > > > sizing > > > > > > has been adjusted. > > > > > > > > > > > > - **Next/Previous Buttons:** 'Next' and 'Previous' navigation > > buttons > > > > > have > > > > > > been implemented on documentation pages to improve sequential > > > browsing. > > > > > > > > > > > > - Several other improvements and refresh including the latest > > > commits. > > > > > > > > > > > > > > > > > > Regards, > > > > > > Harish > > > > > > > > > > > > > > > > > > On Mon, Nov 3, 2025 at 11:38 PM Muralidhar Basani > > > > > > <[email protected]> wrote: > > > > > > > > > > > > > Hi Harish, > > > > > > > Indeed, this is a significant progress. Thank you. > > > > > > > > > > > > > > I have noticed the below on a few pages I was hovering on. > While > > > > these > > > > > > > could be applied on almost all pages. > > > > > > > > > > > > > > General : > > > > > > > 1. Staging link is not fully responsive (mobile, different > > > devices). > > > > > > (Menu, > > > > > > > logo for example) > > > > > > > 2. Favicon and title are not set > > > > > > > > > > > > > > Home page : > > > > > > > 3. I see cards like Manufacturing, Insurance, Telecom etc > > usecases > > > > > which > > > > > > > are screenwide and felt like clickable. On existing docs, these > > > cards > > > > > are > > > > > > > bit small and doesn't feel like they should be nagivated to > some > > > > other > > > > > > > page. And the Manufacturing block is repeated. > > > > > > > 4. Headers are missing in the cards further below > > > > > > > 'Core capabilities' & 'Ecosystem' > > > > > > > I believe it's important to have a title. > > > > > > > > > > > > > > As an example I am using this page for next points. > > > > > > > https://kafka.staged.apache.org/41/streams/introduction/ > > > > > > > > > > > > > > 5. Video embeddings are screen wide. Could be nice if the size > is > > > > > > shrinked > > > > > > > abit. > > > > > > > 6. There is an interactive way to select steps here 'TOUR OF > THE > > > > > STREAMS > > > > > > > API' in existing docs which is missing and videos seem to be > > there > > > > > > without > > > > > > > getting user's attention. > > > > > > > 7. Code snippets > > > > > > > I cannot see or select Java/Scala > > > > > > > 8. Use cases like Zalando, Rabobank are moved to Testimonials > but > > > the > > > > > > cards > > > > > > > are not properly aligned. Could be nice if the card size is > > reduced > > > > > abit > > > > > > > and > > > > > > > 9. In this https://kafka.staged.apache.org/41/streams/ it > could > > be > > > > > nice > > > > > > to > > > > > > > have a lowered font size for 'The easiest way to write > > > > mission-critical > > > > > > > real-time applications and microservices' > > > > > > > 10. Interactive steps are missing for 'Write your First App' > > which > > > > > exist > > > > > > in > > > > > > > existing docs. This gives the user a good overview of the steps > > to > > > be > > > > > > done > > > > > > > before starting. > > > > > > > > > > > > > > https://kafka.staged.apache.org/41/security/ > > > > > > > > > > > > > > 11. Content is repeated for example : > > > > > > > Security Overview > > > > > > > Security Overview > > > > > > > May be some other description if already exists. > > > > > > > > > > > > > > 12. In general on all these category pages, it could be nice to > > > have > > > > > > brief > > > > > > > intro of that the page is about. > > > > > > > Ex on https://kafka.staged.apache.org/41/streams/ > > > > > > > > > > > > > > 13. Pages like Donate ( > > > > > > > https://kafka.staged.apache.org/community/apache/donate/) > > doesn't > > > > lead > > > > > > to > > > > > > > anywhere instead of > > > > https://www.apache.org/foundation/sponsorship.html > > > > > > > > > > > > > > 14. Under the Configuration menu section, it would be > beneficial > > to > > > > > have > > > > > > > submenus such as 'Broker configs' and 'Topic configs'. > > > > > > > > > > > > > > 15. For menu APIs, it would be nice to have submenus. Could be > > > > applied > > > > > > for > > > > > > > all other menus. > > > > > > > > > > > > > > Is it possible to have 'Next' and 'Previous' buttons on pages > > > > > > > > > > > > > > I can imagine we cannot have the exact look and feel and > > > > functionality > > > > > > what > > > > > > > we have in existing docs, but I feel certain aspects are > > important > > > to > > > > > > > achieve here as well to engage the user experience. > > > > > > > > > > > > > > Thanks, > > > > > > > Murali > > > > > > > > > > > > > > On Tue, Nov 4, 2025 at 6:03 AM Harish Vishwanath < > > > > > > [email protected] > > > > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
