provide mathjax

[fmichonneau]

There a few lessons (in the Reproducible curriculum lessons) that use math notation and require MathJax, but it is currently not part of the template.

[rgaiacs]

This is related with https://github.com/swcarpentry/DEPRECATED-bc/issues/521 and https://github.com/swcarpentry/DEPRECATED-lesson-template/issues/121.

@fmichonneau Could you provide me with the link of the episodes that you mentioned? As I mentioned before, I believe that we still can avoid MathJax.

[twitwi]

I've been using equation-in-a-browser for some time (for my slide decks) and I switched to katex as mathjax was very very annoying to bundle and heavy to host or for offline use. Katex is pretty active and has good math support now.

To give an idea, the Katex download is less than 2MB. By keeping only fonts for decents browsers, we can probably go down to around 300kB (unzipped).

[rgaiacs]

@twitwi @fmichonneau I have think about it in the past last days. What do you think of require that pages that are going to use math, only for a math variable or for a very complex equation, must include

require_mathjax: true

in the YAML header?

This will allow us to trigger the inclusion of MathJax or KaTeX only on pages that need it.

[fmichonneau]

I think there are 2 separate issues here:

• supporting a way to render math notations in our lessons
• providing support for this method offline

For this first, I think it would be good to have some kind of support, as currently there is none. I don't know much about the topic, so I'll let people with more knowledge decide whether MathJax, KaTeX, or something else is the best option.

For the second issue, I don't think we should worry about providing offline support for this. It is nice that the current template doesn't need an internet connection to look good, but there are only a handful of places where equations are used/needed, and it doesn't seem that having offline support for those is worth adding a hard coded dependency to our template.

[twitwi]

@rgaiacs Something like require_mathjax is a good idea to limit the footprint of most pages (that don't use any latex). I'd go for something more generic though, like contains_latex_math so we can swap implementations without breaking the semantics of the flag.

I agree that it is most important to have it work online. Offline matters only secondarily. To know if what we can use, @fmichonneau do you have the link to a lesson that uses latex?

[fmichonneau]

See http://www.datacarpentry.org/rr-literate-programming/02-literate-programming/ (middle of the lesson, in the rendered Rmd example on the right there are a few equations)

[fmichonneau]

note that I added MathJax to these pages to render the equations correctly

[rgaiacs]

supporting a way to render math notations in our (online) lessons

I think this is the one that is being block us. We want the page to load fast for the user and for this we need to make the page as smaller as possible.

providing support for this method offline

offline can mean different things for different people. When I say offline, I mean clone the lesson and run it locally with Jekyll. It will not hurt me if we include MathJax/KaTeX on the source code of the lesson.

Side note about EPUB and Kindle, you can't use Javascript! The specification says that you can use but no EPUB/Kindle reader supports Javascript.

[vahtras]

What's the status of math/latex in these templates? When I use another markdown-html renderer it is sufficient to enter this in the markdown file

 <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> </script>

and then math rendering of latex works flawlessly. I would really like that here.

[rgaiacs]

What's the status of math/latex in these templates?

Not included.

As I mentioned on my first comment that point to https://github.com/swcarpentry/DEPRECATED-bc/issues/521 and https://github.com/swcarpentry/DEPRECATED-lesson-template/issues/121, the inclusion of MathJax by default would increase the time for pages to load by half (477ms without Mathjax and 692ms with MathJax, see images). Considering that many lessons will not use LaTeX I'm still against include it by default. If you are the maintainer of one of the lessons you can decide to include it if you want.

If you include MathJax you will probably need to changes things in the "all episodes in one page" that uses JavaScript to inject the content into the page.

Load time

Without MathJax

With MathJax

Load time (slow 3G)

Without MathJax

With MathJax

[jcoliver]

What is the recommended solution to this issue? Over at R for Reproducible Analyses, we have an episode (15) with sub/superscripts and LaTeX math formula example that are not rendered correctly (See "A bit more Markdown" at http://swcarpentry.github.io/r-novice-gapminder/15-knitr-markdown/index.html). We could add require_mathjax: true to the YAML header of the episode, but we are a little concerned about creating downstream problems if Carpentry styles/templates are updated...

[twitwi]

One might want to consider Katex as a lighter alternative. https://katex.org/

[fmichonneau]

fixed with #573