Add KaTeX rendering engine

.coveragerc

@@ -2,14 +2,14 @@
 branch = True
 concurrency = multiprocessing, thread
 parallel = True
-source_pkgs = wagtailmath
+source_pkgs = wagtail-polymath
 omit =
     **/migrations/*
     tests/*
 
 [paths]
 source =
-    src/wagtailmath
+    src/wagtail_polymath
     .tox/py*/**/site-packages
 
 [report]

.github/workflows/ruff.yml

@@ -20,4 +20,4 @@ jobs:
 
     - name: Run ruff
       working-directory: ./src
-      run: ruff --output-format=github wagtailmath
+      run: ruff check --output-format=github

CHANGELOG.md

@@ -11,6 +11,7 @@
   - added tests skeleton
 - Added support for Wagtail 5.2+
 - Dropped support for Wagtail < 5.2, Django < 4.2
+- Rename package to wagtail_polymath
 
 ## 1.2.0 (2021-05-18)
 

MANIFEST.in

@@ -0,0 +1,6 @@
+include CONTRIBUTORS.md
+include CONTRIBUTING.md
+include CHANGELOG.md
+include LICENSE
+include README.md
+recursive-include wagtail_polymath *.html *.png *.gif *js *.css *jpg *jpeg *svg *py

README.md

@@ -13,37 +13,20 @@
 - [Discussions](https://github.com/wagtail-nest/wagtail-polymath/discussions)
 - [Security](https://github.com/wagtail-nest/wagtail-polymath/security)
 
-wagtail-polymath allows you to write equations in your
-[Wagtail](https://github.com/wagtail/wagtail) content using markup and
-render them beautifully.
+`wagtail-polymath` provides robust math typesetting capabilities in LaTeX syntax.
+This project supports multiple typesetting engines, including MathJax and KaTeX, allowing users to choose the one that best fits their needs.
 
-wagtail-polymath provides a `MathBlock` so you can write equations in markup
-(TeX, MathML, ASCIIMath) and render them with MathJax. It features a
-live preview:
+- [LaTeX Syntax Support](https://en.wikibooks.org/wiki/LaTeX/Mathematics): Write complex mathematical expressions using familiar LaTeX syntax.
+- Multiple Typesetting Engines: Currently, [MathJax](https://www.mathjax.org/) (default) and [KaTeX](https://katex.org/) are supported.
+- Live preview.
 
 ![](https://github.com/wagtail-nest/wagtail-polymath/blob/main/docs/images/mathblock.png)
 
-`MathBlock` uses MathJax for rendering so there is very little to do on
-the front end. Simply include the MathJax JS and render the raw
-`MathBlock` content as you would for any other streamfield plain text
-block.
-
-wagtail-polymath even includes a template tag to include the MathJax JS for
-you from a CDN. By default, MathJax is configured to accept all
-recognised markup (TeX, MathML, ASCIIMath) and renders them to HTML. To
-change the configuration, you can pass the desired config command to the
-templatetag. See the [MathJax documentation](https://docs.mathjax.org/en/v2.7-latest/config-files.html#combined-configurations)
-for possible configurations.
-
-For help on using the markup languages see the relevant MathJax
-documentation (e.g. https://docs.mathjax.org/en/v2.7-latest/tex.html) and
-the markup language-specific documentation (e.g. https://en.wikibooks.org/wiki/LaTeX)
-
 ## Quickstart
 
-Install wagtailmath:
+Install wagtail-polymath:
 
-    pip install wagtailmath
+    pip install wagtail-polymath
 
 Add it to your `INSTALLED_APPS`:
 
@@ -52,34 +35,93 @@ Add it to your `INSTALLED_APPS`:
 
 INSTALLED_APPS = (
     # ...
-    "wagtailmath",
+    "wagtail_polymath",
     # ...
 )
 ```
 
 Use `MathBlock` in your `StreamField` content:
 
 ```python
-from wagtailmath.blocks import MathBlock
+from wagtail_polymath.blocks import MathBlock
 
 class MyPage(Page):
-    body = StreamField([
-        ('heading', blocks.CharBlock(classname="full title")),
-        ('paragraph', blocks.RichTextBlock()),
-        ('equation', MathBlock())
-    ])
+    body = StreamField(
+        [
+            ('heading', blocks.CharBlock(classname="full title")),
+            ('paragraph', blocks.RichTextBlock()),
+            ('equation', MathBlock())
+        ],
+        use_json_field=True,
+    )
+
+    content_panels = Page.content_panels + [FieldPanel("body")]
 ```
 
-Use the `mathjax` template tag in your front end template to load the
-MathJax library:
+Use the `polymath_js` template tag in your front-end template to load the typesetting library:
 
 ```django+html
-{% load wagtailmath %}
-...
+{% load wagtail_polymath %}
+
+{# include this line in css block #}
+{% polymath_css %}
+
+{# include this line in js block #}
+{% polymath_js %}
+```
 
-<script src="{% mathjax %}"></script>
+Now you can use LaTeX syntax in your StreamField editor to create mathematical expressions.
+By default, `wagtail-polymath` uses MathJax for rendering, but KaTeX is also supported (see below).
+
+## Settings
+
+### WAGTAILPOLYMATH_ENGINE
+
+If you wants to use KaTeX instead of MathJax, simply add the following line to your Django settings:
+
+```python
+WAGTAILPOLYMATH_ENGINE = "katex"
 ```
 
+This value is set to "mathjax" by default.
+
+### WAGTAILPOLYMATH_SETTINGS
+
+For those who want to specify the CDN provider or for internal site hosting.
+The rendering javascript library path can be customized for different use cases.
+
+Default settings for `MathJax`:
+
+```python
+WAGTAILPOLYMATH_SETTINGS = {
+    "js": [
+        "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-MML-AM_CHTML",
+    ],
+}
+```
+
+Default settings for `KaTeX`:
+
+```python
+WAGTAILPOLYMATH_SETTINGS = {
+    "js": [
+        "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js",
+        "https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js",
+    ],
+    "css": ["https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"],
+}
+```
+
+## Migration from `wagtail-math`
+
+- Django settings:
+  - Replace "wagtailmath" with "wagtail_polymath" in `INSTALLED_APPS`
+- Import section:
+  - Replace "from wagtailmath.blocks import MathBlock" with "from wagtail_polymath.blocks import MathBlock"
+- HTML template:
+  - Replace "wagtailmath" with "wagtail_polymath" in the load section
+  - Add "{% polymath_css %}" to the css block
+  - Replace "<script src={% mathjax %}></script>" with "{% polymath_js %}" in the js block
 
 ## Contributing
 

docs/index.rst

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to wagtailmath's documentation!
+Welcome to wagtail-polymath's documentation!
 =================================================================
 
 Contents:

docs/installation.rst

@@ -4,9 +4,9 @@ Installation
 
 At the command line::
 
-    $ easy_install wagtailmath
+    $ easy_install wagtail-polymath
 
 Or, if you have virtualenvwrapper installed::
 
-    $ mkvirtualenv wagtailmath
-    $ pip install wagtailmath
+    $ mkvirtualenv wagtail-polymath
+    $ pip install wagtail-polymath

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["flit_core >=3.2,<4"]
 build-backend = "flit_core.buildapi"
 
 [project]
-name = "wagtailmath"
+name = "wagtail-polymath"
 authors = [{name = "James Ramm", email = "[email protected]"}]
 description = "Wagtail StreamField block for rendering mathematical equations"
 readme = "README.md"
@@ -52,7 +52,7 @@ Changelog = "https://github.com/wagtail-nest/wagtail-polymath/blob/main/CHANGELO
 Documentation = "https://github.com/wagtail-nest/wagtail-polymath/blob/main/docs/"
 
 [tool.flit.module]
-name = "wagtailmath"
+name = "wagtail_polymath"
 
 [tool.flit.sdist]
 exclude = [

src/wagtail_polymath/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class WagtailPolymathConfig(AppConfig):
+    name = "wagtail_polymath"

src/wagtailmath/blocks.py → src/wagtail_polymath/blocks.py

@@ -2,12 +2,12 @@
 from django.utils.functional import cached_property
 from wagtail.blocks import TextBlock
 
-from .widgets import MathJaxWidget
+from .widgets import PolymathTextareaWidget
 
 
 class MathBlock(TextBlock):
     @cached_property
     def field(self):
-        field_kwargs = {"widget": MathJaxWidget(attrs={"rows": self.rows})}
+        field_kwargs = {"widget": PolymathTextareaWidget(attrs={"rows": self.rows})}
         field_kwargs.update(self.field_options)
         return forms.CharField(**field_kwargs)

src/wagtail_polymath/config.py

@@ -0,0 +1,58 @@
+from django.conf import settings
+from django.contrib.staticfiles import finders
+from django.core.exceptions import ImproperlyConfigured
+from wagtail import VERSION as WAGTAIL_VERSION
+from wagtail.admin.staticfiles import versioned_static
+
+
+TYPESETTING_ENGINE = getattr(settings, "WAGTAILPOLYMATH_ENGINE", "mathjax")
+
+# The path could be static files or external URLs.
+DEFAULT_MATHJAX_SETTINGS = {
+    "js": [
+        "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-MML-AM_CHTML",
+    ],
+    "widget": [
+        "wagtail_polymath/js/polymath-widget-mathjax.js",
+    ],
+}
+
+DEFAULT_KATEX_SETTINGS = {
+    "js": [
+        "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js",
+        "https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js",
+    ],
+    "widget": [
+        "wagtail_polymath/js/polymath-widget-katex.js",
+    ],
+    "css": ["https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"],
+}
+
+if TYPESETTING_ENGINE == "mathjax":
+    DEFAULT_SETTINGS = DEFAULT_MATHJAX_SETTINGS
+elif TYPESETTING_ENGINE == "katex":
+    DEFAULT_SETTINGS = DEFAULT_KATEX_SETTINGS
+else:
+    raise ImproperlyConfigured(
+        f"WAGTAILPOLYMATH_ENGINE: invalid typesetting engine: `{TYPESETTING_ENGINE}` "
+        "(valid options: 'mathjax', 'katex')"
+    )
+
+if WAGTAIL_VERSION >= (6, 0):
+    DEFAULT_SETTINGS["widget"].append(
+        "wagtail_polymath/js/polymath-textarea-controller.js",
+    )
+else:
+    DEFAULT_SETTINGS["widget"].append(
+        "wagtail_polymath/js/polymath-textarea-adapter.js",
+    )
+
+WAGTAILPOLYMATH_SETTINGS = DEFAULT_SETTINGS
+WAGTAILPOLYMATH_SETTINGS.update(getattr(settings, "WAGTAILPOLYMATH_SETTINGS", {}))
+
+
+def get_polymath_config(key):
+    paths = WAGTAILPOLYMATH_SETTINGS.get(key, [])
+
+    # Return absolute path to the asset if it's a static file path.
+    return [versioned_static(path) if finders.find(path) else path for path in paths]

src/wagtailmath/static/wagtailmath/js/mathjax-textarea-adapter.js → src/wagtail_polymath/static/wagtail_polymath/js/polymath-textarea-adapter.js

@@ -1,15 +1,15 @@
 (function() {
-    function MathJaxTextarea(html, config) {
+    function PolymathxTextarea(html, config) {
         this.html = html;
         this.baseConfig = config;
     }
-    MathJaxTextarea.prototype.render = function(placeholder, name, id, initialState) {
+    PolymathTextarea.prototype.render = function(placeholder, name, id, initialState) {
         placeholder.outerHTML = this.html.replace(/__NAME__/g, name).replace(/__ID__/g, id);
 
         var element = document.getElementById(id);
         element.value = initialState;
 
-        initMathJaxPreview(id);
+        initPolymathTextareaPreview(id);
 
         // define public API functions for the widget:
         // https://docs.wagtail.io/en/latest/reference/streamfield/widget_api.html
@@ -22,7 +22,7 @@
                 return element.value;
             },
             setState: function() {
-                throw new Error('MathJaxTextarea.setState is not implemented');
+                throw new Error('PolymathTextarea.setState is not implemented');
             },
             getTextLabel: function(opts) {
                 if (!element.value) return '';
@@ -36,5 +36,5 @@
         };
     };
 
-    window.telepath.register('wagtailmath.widgets.MathJaxWidget', MathJaxTextarea);
+    window.telepath.register('wagtail_polymath.widgets.PolymathTextareaWidget', PolymathxTextarea);
 })();

src/wagtail_polymath/static/wagtail_polymath/js/polymath-textarea-controller.js

@@ -0,0 +1,7 @@
+class PolymathTextareaController extends window.StimulusModule.Controller {
+    connect() {
+        initPolymathTextareaPreview(this.element.id);
+    }
+}
+
+window.wagtail.app.register('polymath-textarea-controller', PolymathTextareaController);