> 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.
That's my current assessment. All the improvements we made recently made a bigger migration less appealing :) > Ideally, navigation and search should work together. We need proper versioned doc support. +1, this would be great. Default search can use `latest` and versioned doc pages can use its own search index. We might be able to do this without any big migrations. Might be worth tracking it to see if anyone is asking for this feature. On Tue, May 26, 2026 at 10:59 AM Steven Wu <[email protected]> wrote: > 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. >> >> >> >> >
