Text to diagrams - Migration of wagtailmath & wagtail-katex

[lb-]

Overview

There are currently three implementations of text to Math diagrams in the Wagtail community, two use Katex and one uses MathJax. All of these are no longer actively maintained but appear to still be popular and have requests for updates, and in some cases PRs, from the community.

In total these are sitting at ~200 package downloads a month collectively, while not huge, it does show there is still interest in these tools even if they do not support the latest versions of Wagtail.

Some developers could implement some of this functionality on their own without too much work but it would be good to provide a community solution to this capability. Additionally, there may be an appetite to extend beyond text to math with other kinds of text to diagram libraries.

Packages

Package / Repo	Question (to merge)	Stats	Stars	Created
wagtailmath	wagtail-nest/wagtail-polymath#11 👍	Stats	30	2017
wagtail-draftail-katex	gatensj/wagtail-draftail-katex#10 🤔	Stats	6	2018
wagtail-katex	ongchi/wagtail-katex#7 👍	Stats	2	2022

General functionality

Each of these packages provides a way for the user to edit the raw text format, usually just a textarea field, and then has the suitable JavaScript library render the output next to it as an SVG (or similar). Along with providing a way to use that same JavaScript library on the main website to do the same.

Proposed plan

1. Decide on the name, either use wagtail-math (with the hyphen) or a more generic name (see below).
2. JamesRamm/wagtailmath GitHub repo moves to wagtail-nest/wagtail-???
3. Use Wagtail cookie cutter to change the project over to that style, will be a large commit but can be managed to preserve some of the history of the existing code.
4. Other package(s) merge commits over into separate branches (to keep history).
5. Integrate behaviour as needed.
6. Community chip in to get to a suitable CI/Release stage.
7. Pypi package prepared (not sure if we can rename/redirect wagtailmath to the new name) and the maintainers plus at least two Wagtail core team members given access to publish.
8. Potential: Use an approach similar to https://github.com/simonw/pypi-rename to get the other names of the packages to 'redirect' to the new one.
9. The other two packages update their READMEs to advise that they are no longer supported and add links to this new repo, potentially marking their repos as archived.
10. Promote/communicate via updates to https://wagtail.org/packages/ & https://github.com/springload/awesome-wagtail & each repo (adding a comment to existing issues).

Scope

Initial scope (proposed)

Essentially the same as the repos above.

• Support two text to math JS engines; MathJax and Katex.
• For each engine, support global config based on the configuration for each library.
• For each engine, support a FieldPanel, widget, Streamfield Block and Draftail block/inline.
• For each engine, support rendering on the within page templates, JS driven, needs to be opt in with scripts.
• Minimal JS tooling, enough for linting but avoid build tooling, rely on cdn assets if possible.
• Wagtail 5.2 (LTS) support, maybe go down to 4.2 or lower if it's possible.

Potential future scope

For ideation only, will require further contributions and consensus and if contributions come through.

• Any other math-like engines that may be suitable.
• Support other diagram engines such as DOT/Graphviz, Mermaid.js, Pintora
• Support some chart / data visualisations such as Vega Lite

Naming (ideas)

• wagtail-math - assume we just want to use roughly the same name (using hyphens) as the oldest/most starred package wagtailmath
• wagtail-abacus - Mathi-ish name but also generic enough to use for other diagram/typesetting.
• wagtail-diagram - Does what it says on the box.
• wagtail-text-to-diagram - Longer name.
• wagtail-pinion - https://www.wordnik.com/words/pinion (the flight feather, a small cog and a few other cool meanings)
• wagtail-plume - https://www.wordnik.com/words/plume
• wagtail-plumage - https://www.wordnik.com/words/plumage
• wagtail-flight - Just generic

[lb-]

Names

Maybe wagtail-polymath Close enough to the wagtailmath name, gives some room to expand if needed and short / to the point. Not bird themed but we can't always have it all.

https://www.wordnik.com/words/polymath

[allcaps]

Merging these packages makes sense to me. They scratch a similar itch. It would be much easier to maintain. The incentive to maintain would also be higher.

But the best motivation is: a one-stop community solution to rule them all. It is for the community / integrators so much nicer to have a single high-value package.

On the other side:

• In development of Wagtail sites, there is often a single specific requirement. So, not all flavours of markup are needed. When merged, each feature should be individually be configurable.
• Same for various dependencies, we should take care to make irrelevant dependencies optional. Nobody likes to install deps they don't use.

Naming suggestions (because I would probably search for these keywords):

• Wagtail Advanced Richtext
• Wagtail Richtext Features
• Wagtail Richtext Math Features

Just a s ref, the download stats:

• https://pypistats.org/packages/wagtailmath
• https://pypistats.org/packages/wagtail-draftail-katex
• https://pypistats.org/packages/wagtail-katex

[lb-]

Great news, Wagtail Math's repo has now moved to https://github.com/wagtail-nest/wagtail-polymath/