I agree with the search change to limit results to the latest version. we don't need to revert it.
I was just saying older version support is only partially working. We can navigate to a older version via url path. But we can't limit search results to the chosen older version. Ideally, navigation and search should work together. We need proper versioned doc support. But I agree that it probably requires significant amount of work to redo the doc site. On Tue, May 26, 2026 at 10:50 AM Max Konstantinov < [email protected]> wrote: > Okay, so as I understand it, it seems like the current state of the > docs is not ideal but satisfactory. The fact that we don't have a very > strong demand for some new feature or a problem that would require a > new doc engine means that we aren't yet ready to invest into a new > engine or using mike for MkDocs. > > 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. > >> >> >
