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