Adds support for mathematical expressions with $ and $$. This is far from standardised, but GitHub now supports math expressions, so I think having an optional extension is justified.
For more context, now that there are more Nx-based packages it's becoming common to write math expressions docs. Math rendering is left to the user (by extending ExDoc), however there are issues if the math is not understood at parser level. For example $x *y* x would be parsed as emphasis, hence destroying the original expression. See https://github.com/elixir-lang/ex_doc/issues/1571.
This implementation should match GitHub for the most part. There are tiny differences, for example:
GitHub parsing has bugs - in the docs they say \$ should work within expression, but it actually only \\$ works
to escape inline math GitHub uses <span>$</span>, but EarmarkParses doesn't support inline HTML; and also I don't see a good reason to not support \$ as with all other delimiters
I looked around and tried to come up with reasonable rules as outlined by the test suite. I also added a note to the docs that this feature is a subject to future changes, it should be fine to do further adjustments as needed, as long as we keep AST compatibility.
As for the AST, I used <code> with .math-inline and .math-display. As far as I can tell, display-style math is generally included within a paragraph (so it's still falls under "inline" parsing). I didn't use <pre> for display-style math because <pre> is not allowed within <p>, but I think that's fine.
Adds support for mathematical expressions with
$and$$. This is far from standardised, but GitHub now supports math expressions, so I think having an optional extension is justified.For more context, now that there are more Nx-based packages it's becoming common to write math expressions docs. Math rendering is left to the user (by extending ExDoc), however there are issues if the math is not understood at parser level. For example
$x *y* xwould be parsed as emphasis, hence destroying the original expression. See https://github.com/elixir-lang/ex_doc/issues/1571.This implementation should match GitHub for the most part. There are tiny differences, for example:
\$should work within expression, but it actually only\\$works<span>$</span>, but EarmarkParses doesn't support inline HTML; and also I don't see a good reason to not support\$as with all other delimitersI looked around and tried to come up with reasonable rules as outlined by the test suite. I also added a note to the docs that this feature is a subject to future changes, it should be fine to do further adjustments as needed, as long as we keep AST compatibility.
As for the AST, I used
<code>with.math-inlineand.math-display. As far as I can tell, display-style math is generally included within a paragraph (so it's still falls under "inline" parsing). I didn't use<pre>for display-style math because<pre>is not allowed within<p>, but I think that's fine.