asciidoctor / asciidoctor

:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
https://asciidoctor.org
Other
4.8k stars 787 forks source link

Introduce a STEM adapter facility #4522

Open mojavelinux opened 10 months ago

mojavelinux commented 10 months ago

Currently, the parser treats STEM content as a passthrough (with some newline processing of AsciiMath). The HTML converter decorates it with a set of delimiters and loads MathJax to find the STEM content and render it. The DocBook converter uses the asciimath gem to convert AsciiMath to MathML and relies on support from the toolchain to handle LaTeX.

There have been numerous requests over the years to process STEM blocks and inlines differently, whether that's to use KaTeX in place of MathJax or to convert the expression to MathML to eliminate the use of a rendering library. This situation is similar to what we have with syntax highlighting. Therefore, I think we should follow the same strategy.

Introduce a STEM adapter facility that allows alternate STEM adapters to be integrated into the processing. An adapter should be able to register for a notation (e.g., asciimath) to start and a backend (e.g., html).

Here are the integration points the adapter should be able to control:

Some adapters may convert the content to an image, so the facility should be able to accommodate that situation.

Note that it is mostly possible to do this today by extending the converter. However, the insertion of the docinfo can be tricky and thus, an adapter is a simpler solution. It can also be distributed as an add-on gem, making it easy for end users to apply.

mojavelinux commented 10 months ago

Consider https://github.com/expeehaa/asciidoctor-mathml as an example use case for an adapter.