[Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Max Konstantinov <ko...@gmail.com>]

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.

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Kevin Liu <ke...@apache.org>]

Removing previous docs from the search index was a recent change, see
https://github.com/apache/iceberg/pull/16368
We can revert it, but I didn't find it helpful when the search result shows
multiple entries for the same term.

BTW `mike` is purely for docs deployment. It's quite opinionated on how to
structure the versioned docs. We currently have a manual process; we build
and push new versions of docs to `docs` branch and `javadoc` branch. IMO
this is working and we shouldn't update it unless there's a benefit to
doing so.

On Tue, May 26, 2026 at 10:27 AM Steven Wu <st...@gmail.com> wrote:

> 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 <ke...@apache.org> 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 <
>> konstantinov.maxim@gmail.com> 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
>>> <de...@iceberg.apache.org> 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 <
>>> konstantinov.maxim@gmail.com> 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.
>>> >>
>>>
>>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Steven Wu <st...@gmail.com>]

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 <ke...@apache.org> 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 <
> konstantinov.maxim@gmail.com> 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
>> <de...@iceberg.apache.org> 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 <
>> konstantinov.maxim@gmail.com> 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.
>> >>
>>
>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Kevin Liu <ke...@apache.org>]

> 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 <st...@gmail.com> 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 <
> konstantinov.maxim@gmail.com> 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 <ke...@apache.org> 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 <
>> konstantinov.maxim@gmail.com> 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
>> >> <de...@iceberg.apache.org> 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 <
>> konstantinov.maxim@gmail.com> 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.
>> >> >>
>>
>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Steven Wu <st...@gmail.com>]

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 <
konstantinov.maxim@gmail.com> 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 <ke...@apache.org> 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 <
> konstantinov.maxim@gmail.com> 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
> >> <de...@iceberg.apache.org> 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 <
> konstantinov.maxim@gmail.com> 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.
> >> >>
>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Max Konstantinov <ko...@gmail.com>]

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 <ke...@apache.org> 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 <ko...@gmail.com> 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
>> <de...@iceberg.apache.org> 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 <ko...@gmail.com> 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.
>> >>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Kevin Liu <ke...@apache.org>]

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 <
konstantinov.maxim@gmail.com> 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
> <de...@iceberg.apache.org> 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 <
> konstantinov.maxim@gmail.com> 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.
> >>
>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Max Konstantinov <ko...@gmail.com>]

> 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
<de...@iceberg.apache.org> 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 <ko...@gmail.com> 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.
>>

Re: [Discuss] Website: Iceberg versioned docs and MkDocs sunset

[Alex Stephen via dev <de...@iceberg.apache.org>]

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 <
konstantinov.maxim@gmail.com> 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.
>
>