add: support for in-Markdown Mermaid diagrams (#525)

* change: bump markdown2 to v2.4.8

* add: mermaid diagram support

docs: include support and example

* docs: grammar

* [autofix.ci] apply automated fixes

* style: fix linting errors

* move mermaid into core pdoc

* mermaid demo: set minimum python version

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Maximilian Hils <[email protected]>

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+ - Add support for rendering [Mermaid diagrams](https://mermaid.js.org/) by passing `--mermaid`.
+   ([#525](https://github.com/mitmproxy/pdoc/pull/525), @thearchitector, @mhils)
  - Add additional Jinja2 blocks to allow a more fine-grained customization of the menu.
    ([#521](https://github.com/mitmproxy/pdoc/pull/521), @mikkelakromann)
  - Fix a crash in pdoc 13.0.0 when `__init__.py` is passed as a file to pdoc.

docs/make.py

@@ -83,6 +83,20 @@
         output_directory=here / "docs" / "math",
     )
 
+    # Render mermaid example
+    pdoc.render.configure(
+        mermaid=True,
+        logo="/logo.svg",
+        logo_link="https://pdoc.dev",
+        edit_url_map={
+            "math_demo": "https://github.com/mitmproxy/pdoc/blob/main/test/testdata/mermaid_demo"
+        },
+    )
+    pdoc.pdoc(
+        here / ".." / "test" / "testdata" / "mermaid_demo.py",
+        output_directory=here / "docs" / "mermaid",
+    )
+
     # Add sitemap.xml
     with (here / "sitemap.xml").open("w", newline="\n") as f:
         f.write(

pdoc/__init__.py

@@ -257,6 +257,12 @@ class GoldenRetriever(Dog):
 [`math_demo`](https://pdoc.dev/docs/math/math_demo.html) for details.
 
 
+## ...render Mermaid diagrams?
+
+Run `pdoc --mermaid`, and pdoc will render mermaid diagrams in your docstrings. See
+[`mermaid_demo`](https://pdoc.dev/docs/mermaid/mermaid_demo.html) for details.
+
+
 ## ...add my project's logo?
 
 See [*Customizing pdoc*](#customizing-pdoc).
@@ -418,6 +424,7 @@ def bark(self, loud: bool) -> None:
   - **[markdown-in-html][]:** Allow the use of `markdown="1"` in a
     block HTML tag to have markdown processing be done on its contents.
     Similar to [PHP-Markdown Extra][] but with some limitations.
+  - **[mermaid][]:** Allows rendering Mermaid diagrams from included Markdown files using <code>```mermaid</code> fence blocks.
   - **[pyshell][]:** Treats unindented Python interactive shell
     sessions as `<code>` blocks.
   - **strike:** Parse `~~strikethrough~~` formatting.
@@ -434,6 +441,7 @@ def bark(self, loud: bool) -> None:
 [footnotes]: https://github.com/trentm/python-markdown2/wiki/footnotes
 [header-ids]: https://github.com/trentm/python-markdown2/wiki/header-ids
 [markdown-in-html]: https://github.com/trentm/python-markdown2/wiki/markdown-in-html
+[mermaid]: https://github.com/trentm/python-markdown2/wiki/mermaid
 [pyshell]: https://github.com/trentm/python-markdown2/wiki/pyshell
 [tables]: https://github.com/trentm/python-markdown2/wiki/tables
 [GitHub-Flavored Markdown]: https://github.github.com/gfm/

pdoc/__main__.py

@@ -96,6 +96,12 @@
     default=False,
     help="Include MathJax from a CDN to enable math formula rendering.",
 )
+renderopts.add_argument(
+    "--mermaid",
+    action=BooleanOptionalAction,
+    default=False,
+    help="Include Mermaid.js from a CDN to enable Mermaid diagram rendering.",
+)
 renderopts.add_argument(
     "--search",
     action=BooleanOptionalAction,
@@ -176,6 +182,7 @@ def cli(args: list[str] | None = None) -> None:
         logo=opts.logo,
         logo_link=opts.logo_link,
         math=opts.math,
+        mermaid=opts.mermaid,
         search=opts.search,
         show_source=opts.show_source,
         template_directory=opts.template_directory,