monty-python icon indicating copy to clipboard operation
monty-python copied to clipboard

Update mistune to v3

Open shiftinv opened this issue 1 month ago • 0 comments

Updates mistune to v3, which resulted in a pretty big refactor being required.

Instead of subclassing BaseRenderer which didn't implement any rendering whatsoever, we now subclass the new MarkdownRenderer and only adjust the ones we need.

Supersedes #777. dependabot could never. c:

Effective changes

For the most part, everything works the same. I did some snapshot testing with the latest 100 issue/pr descriptions in astral-sh/ruff, and all the changes are either whitespace-only, or as follows:

Most importantly, the list renderer now handles some lists better, and reuses parts of mistune's own list item rendering for simplicity.

  • Numbered lists now render properly. Previously, the custom list renderer just assumed everything was an unordered list
  • update: fixed in https://github.com/onerandomusername/monty-python/pull/791/commits/a997b393ae8fb6007b5d3850085f24331786d4f3. leaving this here for posterity: Task lists (i.e. - [x] blah items) ~~don't work anymore~~. This is due to renderer changes[^1], and reimplementing rendering for them isn't trivial due to a bug - https://github.com/lepture/mistune/issues/340
    • While the maintainer in that issue suggests to implement task_list_item, this does not work due to the reasons outlined in the initial issue description. Basically, with how MarkdownRenderer's list rendering works right now, it's fully self-contained and has no knowledge of task lists, and it does not call back to the block renderer that dynamically dispatches token rendering. Unfortunate.
    • Ultimately we might need to monkeypatch mistune.renderers._list._render_list_item, not sure

A probably(?) less important side effect is that newlines between non-rendered elements like HTML or images are now retained, which can result in a bunch of consecutive newlines that would've otherwise been interspersed with HTML tags or image tags. Not sure if/how to fix this.

[^1]: basically, MarkdownRenderer does not implement rendering for any plugin-provided directives. This is also the reason why we e.g. reimplement strikethrough rendering, since it's provided by a plugin.

shiftinv avatar Dec 21 '25 17:12 shiftinv