MkDocs 2.0 will break our docs. What do we do?

[jhkennedy]

MkDocs 2.0 was recently announced and it's going to be a hard pivot, breaking the entire theme and plugin ecosystem.

We depend on a lot of mkdocs plugins:
https://github.com/earthaccess-dev/earthaccess/blob/main/pyproject.toml#L105-L142

And use the mkdocs-material theme, which is now issuing incompatibility warnings and reccomends switching to zensical:
https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

Similarly, some plugins have started issuing warnings when running mkdocs serve like:

WARNING: MkDocs may break support for all existing plugins and themes soon!

The owner of MkDocs has completely abandoned maintenance of the project, and instead is planning to publish a "version
2" which will not support any existing themes, plugins or even your configuration files. This v2 may eventually replace
what you download with `pip install mkdocs`, suddenly breaking the build of your existing site.

To avoid these risks, switch to ProperDocs, a continuation of MkDocs 1.x and a drop-in replacement that supports your
current MkDocs setup.
Simply install it with `pip install properdocs` and build your site with `properdocs build` instead of the MkDocs
equivalents.

Alternatively, to just skip this warning in the future, you can set the environment variable
`DISABLE_MKDOCS_2_WARNING=true`.

For more info visit https://github.com/ProperDocs/properdocs/discussions/33 and https://properdocs.org/

(This warning was initiated by one of the plugins that you depend on.)

and recomending ProperDocs.

It seems like the MkDocs community is fracturing and we'll likely need to pivot to Zensical, ProperDocs, Myst, quarto, or something else entirely.

[mfisher87]

Relevant https://fpgmaas.com/blog/collapse-of-mkdocs/

I've always been a bit frustrated with mkdocs, to be honest, even ignoring the drama and focusing only on its usability and bugs. It's the least fun part of this project to work on for me, and I love docs so I think that's a strong statement 🙃 But the drama has really damaged my trust in the players within this ecosystem of projects (Mkdocs, ProperDocs, Zensical).

I propose that we switch to Sphinx. I don't know of any project that can compare to its autodocumentation functionality, and the pydata theme is just fine. I don't like conf.py or the pattern of introducing Make into the build chain, but I think those concerns are fairly trivial compared to the risk & cost of adopting a brand new documentation engine. I'd like to advocate for MyST, and I do love MyST, but I don't think it's ready to meet our autodoc or navigation needs. Sphinx is capable and proven and stable. I also find sphinx extensions very easy to write (or for an LLM to write).

[asteiker]

@jhkennedy Thank you for getting this on our radar! I couldn't quickly find a release date, or a date in which v1.x will be completely deprecated. Have you seen more info on their timeline?

@mfisher87 What do you think it will take for us to migrate to another package like sphinx? This feels like something we'll want to utilize our decision committee for.
Edit: Decision label is already on here, nm!

[jhkennedy]

@mfisher87 good point on sphinx, not sure how I missed that in my list! 🤦

I agree autodoc-ing is probably the best in sphinx right now. I'm not a fan of reStructuredText, but the markdown extension seems to work a lot better now, and support for rst here and in other tools has gotten a lot better as well.

I couldn't quickly find a release date, or a date in which v1.x will be completely deprecated. Have you seen more info on their timeline?

@asteiker that's part of the problem -- it's a long ways out but there hasn't really be communication from the owner on when this rollout will happen, or what the roadmap/features will actually look like.

This feels like something we'll want to utilize our decision committee for.
Edit: Decision label is already on here, nm!

@asteiker @mfisher87 I'm not 100% sure we need to use the formal decision committee here -- I'm fine with "whoever wants to do the work can decide" but I did add the label because it will be a pretty big decision.

[mfisher87]

I use Sphinx all the time and never use RST ;) Except for autodoc, which is only a few lines, and I'm not sure why it weirdly forces the use of RST.

Another options is pinning mkdocs <2; what we have is working despite my complaints ;)

[jhkennedy]

Another options is pinning mkdocs <2...

I think we want to do this short term for sure. Zensical and/or PropperDocs may be a drop in replacement by the time issues actually crop up.

But, I do think this is a good oppertunity to re-evaluate how we're doing our docs. Sphinx is pretty battle tested, stable, and has a good developer community, so it's pretty hard to argue with that.

[mfisher87]

Sphinx is pretty battle tested, stable, and has a good developer community, so it's pretty hard to argue with that.

💯 And extensible! (mkdocs 2 won't support plugins! wat!)

[weiji14]

I would have voted Zensical (on technical merit) since it's the spiritual successor to Material for Mkdocs (and it has backward compat with mkdocs.yml). Most of the plugins I see in https://github.com/earthaccess-dev/earthaccess/blob/v0.16.0/mkdocs.yml should be in Zensical already, except mkdocs-jupyter which is not supported yet (zensical/zensical#52), so...

+1 for Sphinx or MyST if wanting to keep writing jupyter notebooks.

Edit: I read the blog post linked above at #1264 (comment), and now think it might be good to stay away from the mkdocs (or successor) ecosystem until the dust settles... the open source culture there doesn't bode well with what I feel earthaccess or jupyter stands for.