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. >> >> >> >
