"Native" Support for Math Rendering with `html` Output

[carloskiki]

Problem

Using Math within a MdBook is currently subpar, since it requires either using an unconventional syntax to render with MathJax, or a preprocessor which is slower (having to do 2 passes) and janky. Now that pulldown-cmark supports mathematical rendering directly, I propose using its much more conventional syntax ($ and $$) for markdown math. What follows can be seen as a tiny RFC for first class math in markdown support.

Proposed Solution

Overview

pulldown-cmark with version >=0.11.0 has native support for math in markdown. MdBook could make use of this feature to have better support for math using a more conventional syntax, and allow arbitrary 3rd party renderers to render math to html more efficiently.

Technical Details

A configuration option: math-renderer, would be added to the [output.html] table, which would accept any of the following values:

[output.toml]
math-renderer = "simple-command" # A simple command to parse and render the LaTeX provided into html.
math-renderer = ["array", "of", "command", "arguments"] # A command consisting of multiple arguments, specified as an array of strings.

If no math-renderer is provided and some $ (or $$) math is encountered, MdBook could either error or output it as normal text.

Renderer Command

The command would be given the string of $\LaTeX$ (or another mathematical format) from stdin, and would be expected to output the html to stdout. Checks would be added to make sure the command does not hang.

Unresolved Questions

• [ ] If the command returns with a status other than 0, should MdBook error?
• [ ] Should we verify the generated html from the math-renderer command?
• [ ] Should we error if a book contains markdown math but has not specified a command for it?

Notes

If this feature gets positive feedback, I am willing to spend time implementing it.

[carloskiki]

Note on Backwards Compatibility: This change can be made backwards compatible, by still allowing the legacy MathJax support and later deprecating it.

[carloskiki]

@rustbot claim