: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.
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:
conversion of content, including added delimiters (method: convert)
docinfo insertion (content and location) (method: docinfo)
format of enclosing element (to add hints like a CSS class or data attribute) (method: format)
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.
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.