Render math with MathJax

[miketheman]

No description provided.

[miketheman]

I split into commits to make review easier (I hope). Each commit has more detailed descriptions.

I chose to use the CDN approach over trying to load an npm package and further expand the current packaged javascript, so as to keep the page loading fast and allow for async loading of the added code. A tradeoff is expanding the CSP rules to accommodate, at least until we come back to the frontend pipeline and potentially using more of webpack to split up the client code a little more.

[miketheman]

Here's what it looks like with the SVG renderer, and using the Accessibility extensions to expand/collapse.

Screen.Recording.2022-08-06.at.6.47.32.PM.mov

Also loads the screen reader plugin in the background.

[di]

I think I'd rather just host the JS ourselves. We could just serve the JS bundle as a static asset similar to our other JS assets if we wanted to avoid mucking about with the frontend pipeline.

[miketheman]

@di I tinkered with it and think I got it right in 8334ac9

I didn't vendor the entire mathjax package, only the files necessary to load and render tex-style and svg output - if we need more than that, we'll have to add those files.

Changed: I moved the loading script tag to only load on warehouse/templates/packaging/detail.html where it's expected to be used, so other parts of the site don't have to load it.

[miketheman]

CodeQL doesn't like the inclusion of the compiled module - uncertain what the implications of that are.

[ewdurbin]

I’m -1 on rendering this with JS client side as it kinda defeats the purpose of readme_renderer, which is to reduce the ability for user content to interact with PyPI sessions, which this opens us up to if some vuln exists with the library.

To address the request for math rendering to match GFM, I’d be more interested to see it implemented as part for cmark/cmarkgfm.

I haven’t looked but I suppose this is moot if it’s what GitHub is doing I’d trust the addition of the client side code more readily.

[ewdurbin]

Carry on 😂 https://github.blog/2022-05-19-math-support-in-markdown/

[miketheman]

@ewdurbin Thanks. I've been digging through this, and following the current practices on GitHub.

This change is specifically for RST right now - GFM is not addressed (yet).

[ewdurbin]

I’m not really opposed to loading the library from CDN given the integrity checks, is there a particular reason you flagged it for vendoring @di?

[miketheman]

To address the request for math rendering to match GFM, I’d be more interested to see it implemented as part for cmark/cmarkgfm.

@ewdurbin GFM is tracked in pypa/readme_renderer#214

[di]

I’m not really opposed to loading the library from CDN given the integrity checks, is there a particular reason you flagged it for vendoring @di?

Just inherent distrust of third party CDNs and the JS ecosystem I guess 🙂. There's a lot that could be hosted on JSdeliver and it felt like overkill to poke so many holes in our CSP for it.