Change markdown implementation.

Python-commonmark is deprecated, and recommends markdown-it-py instead.

This commit also introduces an abstract muppet.markdown module to allow
easier switching in the future, and enables id's for all headers in the
generated HTML.

4 files changed, 58 insertions, 8 deletions

diff --git a/muppet/format.py b/muppet/format.py
index 67aa555..97c38d1 100644
--- a/muppet/format.py
+++ b/muppet/format.py
@@ -6,7 +6,7 @@ provided as the first element. This program goes through every
 definition in it, and outputs a complete index.html.
 """
 
-from commonmark import commonmark
+from .markdown import markdown
 from subprocess import CalledProcessError
 import html
 import sys
@@ -1067,13 +1067,13 @@ def print_docstring(name: str, docstring: dict[str, Any]) -> str:
     #         if text := t.get('text'):
     #             text = re.sub(r'(NOTE|TODO)',
     #                           r'<mark>\1</mark>',
-    #                           commonmark(text))
+    #                           markdown(text))
     #             out += f"<dd>{text}</dd>"
     # out += '</dl>'
 
     if 'text' in docstring:
         out += '<div>'
-        out += commonmark(docstring['text'])
+        out += markdown(docstring['text'])
         out += '</div>'
 
     return out
@@ -1101,7 +1101,7 @@ def build_param_dict(docstring: dict[str, Any]) -> dict[str, str]:
                 if text := t.get('text'):
                     obj[t['name']] = re.sub(r'(NOTE|TODO)',
                                             r'<mark>\1</mark>',
-                                            commonmark(text))
+                                            markdown(text))
         return obj
     else:
         return {}
diff --git a/muppet/markdown.py b/muppet/markdown.py
new file mode 100644
index 0000000..df54fee
--- /dev/null
+++ b/muppet/markdown.py
@@ -0,0 +1,49 @@
+"""
+Muppet central markdown module.
+
+This module exports one procedure, ``markdown``. This to easily
+configure all markdown rendering to be the same in one central place,
+and to allow "easy" switching of the markdown engine.
+"""
+
+from markdown_it import MarkdownIt
+from mdit_py_plugins.anchors import anchors_plugin
+
+
+def markdown(text: str) -> str:
+    """
+    Render the given markdown string to HTML.
+
+    The current implementations sets these options and plugins:
+
+    html
+        Enable HTML in the source, which will be passed verbatim
+
+    linkify
+        Things which looks like links will be hyperlinked
+
+    anchors_plugin
+        Each header will get an appropriate id-attribute set, allowing
+        hyperlinks to it.
+
+    table
+        Allow markdown tables.
+
+    strikethrough
+        Allow GFM-like strikethrough (``~~striken out~~``).
+
+    :param text:
+        A Markdown string.
+
+    :returns:
+        A HTML string.
+    """
+    md = MarkdownIt('commonmark', {'html': True, 'linkify': True}) \
+        .use(anchors_plugin) \
+        .enable('table') \
+        .enable('strikethrough')
+
+    return md.render(text)
+
+
+# header_text.downcase().replace(' ', '-')
diff --git a/muppet/output.py b/muppet/output.py
index 242b3b5..0e83c58 100644
--- a/muppet/output.py
+++ b/muppet/output.py
@@ -14,7 +14,7 @@ from jinja2 import (
     FileSystemLoader,
 )
 from .lookup import lookup, Ref
-from commonmark import commonmark
+from .markdown import markdown
 from .format import (
     format_class,
     format_type_alias,
@@ -103,7 +103,7 @@ def index_item(obj: dict) -> IndexItem:
     }
 
     if summary:
-        out['summary'] = commonmark(summary)
+        out['summary'] = markdown(summary)
 
     return out
 
@@ -356,7 +356,7 @@ def setup_module(base: str, module: ModuleEntry, *, path_base: str) -> None:
         pathlib.Path(os.path.join(path, name)).mkdir(exist_ok=True)
         out_path = os.path.join(path, name, 'index.html')
 
-        content = commonmark(raw_content)
+        content = markdown(raw_content)
         template = jinja.get_template('content.html')
         crumbs = breadcrumbs(('Environment', ''),
                              module.name,
diff --git a/setup.cfg b/setup.cfg
index 9192dda..8d2416d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -29,6 +29,7 @@ packages = muppet
 python_requires = >= 3.10
 install_requires =
 	jinja2~=3.1.2
-	commonmark~=0.9.1
+	markdown-it-py~=2.2
+	mdit_py_plugins=~0.3
 setup_requires =
 	setuptools