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