Add optional support for math syntax #142
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jonatanklosko
commented
Nov 24, 2023
| @@ -25,6 +25,7 @@ | |||
| - [Pure links](#pure-links) | |||
| - [Wikilinks...](#wikilinks) | |||
| - [Sub and Sup HTML Elements](#sub-and-sup-html-elements) | |||
| - [Mathematical expressions](#mathematical-expressions) | |||
There was a problem hiding this comment.
I couldn't find the readme task, so I mirrored the changes from moduledoc manually. Let me know if/how I should generate it :)
There was a problem hiding this comment.
Done it is mix xtra I guess I should document that somewhere, maybe contribution notes/rules?
There was a problem hiding this comment.
Ah it comes from an external package, that makes sense, thanks!
josevalim
approved these changes
Nov 24, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 elixir-lang/ex_doc#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.