LaTeX math rendering in Markdown blocks

[danijar]

KaTeX and MathJax seem like great options.

Current status: LaTeX is included by default now. However, it is loaded from a URL and we are working on bundling a local copy with the package for offline viewing.

[danijar]

Working prototype:

import handout
doc = handout.Handout('handout')
doc.add_html('<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML" async></script>')
"""
$$f(x)=\int x^2 \ \mathrm{d}x$$
"""
doc.show()

[bymayanksingh]

I have tested latex equations by adding in cdn script as on line 13, It works quite well... is something else also expected from this issue?

[danijar]

Great to hear. It works well for me, too. I want to include a local copy of the MathJax script by default, so that users don't have to add the line and the handout also renders correctly without internet access. Feel free to create a PR for it if you have a chance.

[bymayanksingh]

@danijar I am interested in solving this issue.

I have this workflow in mind:

• install mathjax library using npm install mathjax in data directory.

• add following script with Tex supported configuration in _generate function.
  <script type="text/javascript" src="node_modules/mathjax/MathJax.js?config=TeX-MML-AM_CHTML"></script>

• also copy node_modules directory from src data directory to output directory by making changes in show function.

• make changes in example.py to test actual LaTex Math equations.

• add installation instructions for additional dependency mathjax in README.md.

is this workflow fine? if you think we can do something else in here, please do suggest.

[danijar]

Thanks! How about just bundling a copy of MathJax the same way the other scripts are bundled? I think updating it every now and then is easy enough and would keep the dev workflow easier and code complexity lower.

Users should definitely not have to install anything manually to get MathJax support. In other words, a light Python package is fine to add as dependency, but requiring users to have a node package manager is not.

[boffi]

Having LaTeX math in Markdown blocks is nice, having Latex math generated by Python code is even nicer because you can present the output of calculations in what is (sometimes) the most appropriate format, i.e., a nicely formatted mathematical notation.
Jupyter notebook can handle that with

string_of_latex_commands = lots_of_computations()
display(Math(string_of_latex_commands))

in Handout maybe doc.Math(string_of_latex_commands) or something like that.

[bymayanksingh]

@danijar mathjax script is bundled as a zip and upon extraction all the files size to ~69 MB, is there any way I can minify it, since it will become an overhead upon copying it from data dir to output dir, also it makes handout slow.

[danijar]

That's more than I expected. Do you know how KaTeX compares?

[bymayanksingh]

KaTex is really small in comparison ~3.2MB , I am still finding a way to make it work locally as for some reason even it's CDN script doesn't work on my end.

[danijar]

KaTeX requires including a style file and initializing it by calling a JavaScript function as far as I know.

[danijar]

I played around with including KaTeX but it seems to not play as nicely with our Markdown renderer marked.js. I found a compatibility script but online display equations and equations inside paragraphs would render, not for example in bullet lists.

For now I added MathJax from the CND in the latest release to cover the most common use case. Looking around it seems possible to create a more lightweight distribution of MathJax to bundle with Handout, which would be great to include in the next/a future release.

[bymayanksingh]

@danijar yes, even I was playing around with KaTex but the results were not satisfactory for me, even when I managed to somehow get KaTex working, it still didn't render the fonts nicely.
It's good that you added MathJax CDN as I was about to suggest you the same for now, also should we leave this issue open ?

[danijar]

Thanks for also taking a look. Yes, let's leave this open. It would be great to bundle a stripped down version of MathJax because I think it can be frustrating to users if their document suddenly doesn't render anymore when they're offline. I think the browser cache could mitigate this a bit, but relying on that seems risky. If you're interested, it'd be great if you could look into how small we can get a local version of MathJax. There seem to be a couple of tools that people wrote to minify and strip away unnecessary parts of the MathJax repository.

[bymayanksingh]

sure, I will take a look into it.