Removing previous docs from the search index was a recent change, see https://github.com/apache/iceberg/pull/16368 We can revert it, but I didn't find it helpful when the search result shows multiple entries for the same term.
BTW `mike` is purely for docs deployment. It's quite opinionated on how to structure the versioned docs. We currently have a manual process; we build and push new versions of docs to `docs` branch and `javadoc` branch. IMO this is working and we shouldn't update it unless there's a benefit to doing so. On Tue, May 26, 2026 at 10:27 AM Steven Wu <[email protected]> wrote: > While the navigation to older doc versions [2] works, search is limited > only to the latest version which is unintuitive. > > [2] https://iceberg.apache.org/docs/1.10.2/ > > On Tue, May 26, 2026 at 10:22 AM Kevin Liu <[email protected]> wrote: > >> Thanks for starting this thread, Max. >> >> MkDocs is indeed abandoned. We get a warning message about it during >> building the docs. However, we pin to and still use an older version of it. >> It gets the job done :) >> >> With regards to versioned docs, I opened the issue [1] to explore `mike`. >> It can potentially help us simplify the docs deployment process. However, >> it does seem like a really big lift. Given the recent improvements to the >> overall docs process, it might not be worth it to migrate to `mike`. >> >> As for the versioned dropdown, I really like the idea. But again, it >> might not be worth the effort. Users can already navigate to older versions >> of the doc [2] >> >> Best, >> Kevin Liu >> >> [1] https://github.com/apache/iceberg/issues/14521 >> [2] https://iceberg.apache.org/docs/1.10.2/ >> >> On Mon, May 25, 2026 at 4:36 PM Max Konstantinov < >> [email protected]> wrote: >> >>> > Can you explain more about what’s missing from our versioned docs? We >>> can get some documentation from prior releases (example: >>> > https://iceberg.apache.org/docs/1.9.2/configuration/). The bug you >>> mentioned was about some issues with over-indexing, but it sounds like >>> those have been solved. >>> >>> Oh, yes, let me clarify. By versioned docs I meant the one with a >>> dropdown selector that switches the current version of the docs, that >>> idea surfaced in that email thread I referenced and current related >>> issue propose to use mike for it. >>> >>> > I personally would love to move towards a different documentation >>> engine, but it’s a lot of work! I think the community would need really >>> strong use cases that we couldn’t easily support in mkdocs to attempt a >>> migration. Any ideas? >>> >>> I started looking into mike integration, which would enable the >>> dropdown selector but then realized that mike is based on MkDocs and >>> wanted to make sure that the effort put into mike integration won't be >>> a waste. Atm I'm trying to understand our stance on adding new docs >>> related features considering the fact that Iceberg's current >>> documentation engine, MkDocs, is being abandoned. >>> >>> >>> On Mon, May 25, 2026 at 3:58 PM Alex Stephen via dev >>> <[email protected]> wrote: >>> > >>> > Hi Max, >>> > >>> > Thanks for kicking off this conversation! >>> > >>> > Can you explain more about what’s missing from our versioned docs? We >>> can get some documentation from prior releases (example: >>> > https://iceberg.apache.org/docs/1.9.2/configuration/). The bug you >>> mentioned was about some issues with over-indexing, but it sounds like >>> those have been solved. >>> > >>> > I tried using mike for iceberg-python and came back frustrated. The >>> mike CLI is very opinionated and wants to make commits for you (‘mike >>> deploy’). This ended up not working well in our use-case. >>> > >>> > I personally would love to move towards a different documentation >>> engine, but it’s a lot of work! I think the community would need really >>> strong use cases that we couldn’t easily support in mkdocs to attempt a >>> migration. Any ideas? >>> > >>> > Thanks! >>> > — Alex Stephen >>> > >>> > On Mon, May 25, 2026 at 2:48 PM Max Konstantinov < >>> [email protected]> wrote: >>> >> >>> >> Hi All! >>> >> >>> >> >>> >> Background >>> >> - MkDocs community has broken down over the last couple of years, and >>> the project seems abandoned. You can see 0 new contributions during the >>> last 1.5 years: >>> https://github.com/mkdocs/mkdocs/graphs/contributors?from=5%2F18%2F2024. >>> You can find the description and discussion of the whole kerfuffle on >>> HackerNews' thread from March 2026 if you are interested, all previous >>> maintainers moved on to new projects. >>> >> - Iceberg community wanted to add versioned docs support to the >>> Iceberg website, see a recent thread where the need for versioned docs >>> surfaced a week ago: >>> >> https://lists.apache.org/thread/vrt3oytl3dwo34wr07tkf73r0kkx0b1h. >>> >> >>> >> Questions >>> >> - Do you think it is still worth pursuing mike route for versioned >>> docs as it is based on MkDocs? See a related Iceberg issue: >>> https://github.com/apache/iceberg/issues/14521 >>> >> - Do you think we should look for a new doc engine altogether instead >>> of MkDocs? >>> >> >>> >> >>> >> Thanks, >>> >> Max. >>> >> >>> >>
