Add support for additional markdown extras / mermaid

[thearchitector]

Problem Description

GitHub supports rendering Markdown files with Mermaid diagrams, which aren't supported by default with markdown2 and thus don't get translated correctly.

It seems like a pretty common use case to include your project's README in your module's top-level docstring. Since the diagram doesn't render, I've found that I need to maintain 2 copies of the README, one using the mermaid fence block syntax and another with a static <img> of the diagram (and making them both an img doesn't work since the img doesn't respond to GitHub's theme changes).

Proposal

This proposal requires bumping the vendored version of the markdown2.

More recent versions have built-in support for rendering mermaid diagrams via the mermaid extra. The extra requires some additional HTML stuff, but I don't think that needs to be included in default template (people can add the necessary JavaScript themselves via a custom template, maybe with a doc explaining how to do it).

Alternatives

Rather than always enable the mermaid extra and having to maintain the list of extras enabled, more recent versions of markdown2 also support enabling extras from within a markdown document via the use-file-vars extra. Adding that one extra would let people customize the rendering of their markdowns themselves rather than either fork this project or find another solution.

[mhils]

I'd be happy to merge a PR that bumps markdown2, and I'd also be happy to enable the mermaid extra by default. 👍

The extra requires some additional HTML stuff, but I don't think that needs to be included in default template (people can add the necessary JavaScript themselves via a custom template, maybe with a doc explaining how to do it).

This sounds about right. We definitely don't want to pull in stuff from third parties by default. But adding this with an "How can I ...?" entry on https://pdoc.dev/docs/pdoc.html and optionally an example in ./examples would be great! Do you want to send a PR?

more recent versions of markdown2 also support enabling extras from within a markdown document via the use-file-vars extra.

One problem here is that we render each docstring individually, so you'd need to repeat that string a lot. If you need to customize the included extras, it's probably more convenient to write a small Python script that patches https://pdoc.dev/docs/pdoc/render_helpers.html#markdown_extensions and then calls pdoc.pdoc(...). But again, for the specific case of the mermaid extra there's no harm in enabling it by default. 😃

[thearchitector]

Sure! I'll put together a PR with the version bump and doc updates. Re file-vars, since each doc is separate then that makes sense to me -- at a certain point the granularity required would probably exceed the benefit of the customizability.

Clarifying question -- is there a reason that markdown2 is vendored instead of just listed as a dependency?