Upgrade mistune to v3

[dotlambda]

The list changes can be found here: https://github.com/lepture/mistune/blob/master/docs/changes.rst
There is an upgrade guide: https://mistune.lepture.com/en/latest/upgrade.html

[dairiki]

How imperative is it to get to this soon?
Are there any new "must have" features in mistune 3?
(Type annotations is a big one for me.)

(I must say that it's sort of frustrating how each new version swaps the order and names of the arguments to the renderer methods.)

(As long as we have to update code for a new API, are there other markdown rendering libraries we should consider switching to? Is mistune still the fastest?)

[dotlambda]

How imperative is it to get to this soon?

It's not super relevant. It will just get more important as other packages move to mistune v3.

Are there any new "must have" features in mistune 3?

I don't think so. I'm only concerned about being able to install lektor besides other packages depending on mistune.

[dairiki]

I don't think so. I'm only concerned about being able to install lektor besides other packages depending on mistune.

The recommended way to install Lektor is in a virtual environment (e.g. using pipx, see #915). In that case, there should be no mistune dependency conflicts (unless one is using a Lektor plugin that depends on mistune > 2).

On a related note, because the mistune API changes so much between major releases, it makes it very tricky to migrate Lektor in a way that doesn't break any existing Lektor plugins that extend mistune. (See, e.g. #992, #1134).

[nixjdm]

It's possible for mistune to grow a list of community plugins that might be v3+ only, too, but right now there are no such plugins listed on the project, so I wouldn't call that urgent.

I haven't tested our various markdown plugins on v3 to see if they break or not, or if they have version ceilings on mistune. It's not necessary to get a working project if they pull in v3 and that breaks, but some patch releases might be in order to make UX a little less frustrating for folks.

[nixjdm]

(As long as we have to update code for a new API, are there other markdown rendering libraries we should consider switching to? Is mistune still the fastest?)

Always a good question to revisit. I know in the past I've seen interest in making the renderer swap-able generally, too. A topic for another thread, perhaps.