Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for mathematical expressions in Markdown #12009

Closed
claudiodsf opened this issue Aug 3, 2022 · 4 comments · Fixed by #12149
Closed

Support for mathematical expressions in Markdown #12009

claudiodsf opened this issue Aug 3, 2022 · 4 comments · Fixed by #12149
Labels
blocked Issues we can't or shouldn't get to yet feature request

Comments

@claudiodsf
Copy link

What's the problem this feature will solve?
GitHub has started supporting mathematical expressions in Markdown.
It would be nice to have the same possibility in PyPi, since oftentimes the README.md on GitHub is used as long_description in setup.py.

Describe the solution you'd like
Implement the same syntax used by GitHub, described here.

Additional context
Example PyPi package for which math expressions are not rendered: https://pypi.org/project/sourcespec/ (section: "Theoretical background").
The original README.md on GitHub: https://github.com/SeismicSource/sourcespec/blob/master/README.md

@claudiodsf claudiodsf added feature request requires triaging maintainers need to do initial inspection of issue labels Aug 3, 2022
@miketheman
Copy link
Member

Related: pypa/readme_renderer#214

@di
Copy link
Member

di commented Aug 12, 2022

This is blocked on pypa/readme_renderer#214 (but this does work for reStructuredText now since #12062)

@di di added blocked Issues we can't or shouldn't get to yet and removed requires triaging maintainers need to do initial inspection of issue labels Aug 12, 2022
@miketheman
Copy link
Member

🥳 I'm very excited to report that the work done to enable MathJax on the frontend now automatically detects the $$ delimiters that have been added in the Markdown, so no changes to either readme_renderer or warehouse code are necessary!

Using the provided project, we can now see that the previously submitted content renders as Math (that I don't fully understand, but who cares?! 😆 ):
Screen Shot 2022-08-26 at 18 12 00

Note in particular that the . . . in-line delimiters are not used by default. That is because dollar signs appear too often in non-mathematical settings, which could cause some text to be treated as mathematics unexpectedly. For example, with single-dollar delimiters, “… the cost is $2.50 for the first one, and $2.00 for each additional one …” would cause the phrase “2.50 for the first one, and” to be treated as mathematics since it falls between dollar signs.

We could add them as configuration, if we want: https://docs.mathjax.org/en/latest/input/tex/delimiters.html#tex-delimiters

but should consider the potential downsides of a sentence like:

To split $100 in half, we calculate $100/2$

GitHub docs recommend using html to split and make it work like so:

To split <span>$</span>100 in half, we calculate $100/2$

We'd have to ask ourselves what's the likelihood of an equation being inline with an expected dollar sign.

@claudiodsf
Copy link
Author

Wow, that's great! Thank you!

For the inline dollar sign problem, I think that the benefits of having inline LaTeX outweigh the corner case of a dollar sign in the same sentence.

I would say that people who chose to use LaTeX math in their README.md will probably detect this problem when rendering locally or on GitHub/GitLab their markdown file, which will push them to try and find a solution on their own.

Moreover, it would be nice, from my point of view, if we match the GitHub syntax, and thus allow inline LaTeX.

Great work, anyway! Thanks again!

miketheman added a commit to miketheman/warehouse that referenced this issue Aug 30, 2022

Unverified

No user is associated with the committer email.
We can configure MathJax to detect the convention of single dollar signs
in addition to its other methods, as it's not on by default.

The inline script needs to be supported by our CSP, and if the stanza
ever changes, we'll need to recalculate the hash and update the CSP
accordingly.

Resolves pypi#12009
Resolves pypa/readme_renderer#214

Signed-off-by: Mike Fiedler <miketheman@gmail.com>
ewdurbin added a commit that referenced this issue Aug 30, 2022

Verified

This commit was signed with the committer’s verified signature.
atanmarko Marko Atanasievski
We can configure MathJax to detect the convention of single dollar signs
in addition to its other methods, as it's not on by default.

The inline script needs to be supported by our CSP, and if the stanza
ever changes, we'll need to recalculate the hash and update the CSP
accordingly.

Resolves #12009
Resolves pypa/readme_renderer#214

Signed-off-by: Mike Fiedler <miketheman@gmail.com>

Signed-off-by: Mike Fiedler <miketheman@gmail.com>
Co-authored-by: Ee Durbin <ewdurbin@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
blocked Issues we can't or shouldn't get to yet feature request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants