r-lib
Should it be easier to not load MathJax/to tweak the version?
At the moment to not have MathJax or to load a different version one needs to override the head.html template.
Should it be easier to not include MathJax? E.g. providing an opt-out.
From looking at https://github.com/r-lib/pkgdown/blob/main/inst/BS5/templates/head.html, I see no other element that's loaded everywhere but not useful everywhere.
I know this was discussed following #1566 but without the aspect that one can't choose another version.
Cc @jeroen
I think ideally we be able to specify a mathjax_version in overrides, and also be able to set it to false for no mathjax.
I think it's mostly just faster: https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html Perhaps it doesn't work as well on some very old browsers.
So why do more than updating mathjax in pkgdown? That seems like it would be easier?
It's still very heavy and only used by a handful of packages, we prefer to make it opt-in for rOpenSci. But we can make this work by shipping a custom head.html in our template, so not super important.
There are two commits from an abandoned PR branch that might be helpful when updating MathJax to v3: https://github.com/r-lib/pkgdown/pull/1541/commits/39f001edf6de10b097240c719c0f063d09bec274 and https://github.com/r-lib/pkgdown/pull/1541/commits/63af614f95f8fac8c46b1c01f8c8bc7fab1deaf0
The tex-mml-chtml MathJax 3.1.2 component is used there (which of course is outdated meanwhile).
Are there that many differences between mathjax versions?
FYI Yes version 3.0 has completely different configuration than version 2.0. For example, the MathJax configuration java-script that you use to turn on equation numbers is completely different between the two versions.
Should we switch from mathjax to mathml? It looks like it's well supported by all major browsers (https://caniuse.com/mathml), and it would eliminate an external dependency.
(We could default to mathml, but still allow folks to switch back to the previous mathjax approach if mathml didn't work for them)
I mathjax is needed to convert latex to mathml? If you want something in R, katex::katex_mathml() or katex::katex_html allow you to eliminate the browser-side javascript dependencies, see the vignette
Is there some reason not to use pandoc's mathml conversion? https://pandoc.org/MANUAL.html#math-rendering-in-html
Is there some reason not to use pandoc's mathml conversion? https://pandoc.org/MANUAL.html#math-rendering-in-html
I guess it would absolutely make sense to use Pandoc for this. If we rely on Pandoc for the conversion, why not give users the choice to opt in to --katex or --mathjax instead of the (new) default --mathml?
While the future appears to belong to MathML, browser support is still somewhat rudimentary compared to KaTeX/MathJax. See Pandoc's math demo pages (in your preferred browser) for a rendering quality comparison:
Another nice browser math engine comparison site: https://mk12.github.io/web-math-demo/ (last updated on Apr 14, 2022; for the used asset versions, see https://github.com/mk12/web-math-demo/blob/main/index.html#L99-L119)
The main reason not to expose more math rendering options is that it's potentially a bunch of work that few people would benefit from.
@Bisaloo looks like maybe you have some experience with this?
No sorry, I don't know enough to help with this
Looks like we'll need to use some basic markdown file with a custom template (see below) in order to extract the version of mathjax that pandoc uses. If we're doing that, then it does probably make sense to support at least katex, since we'd need to do the same thing. We could capture this info in a similar way to build_bslib(), doing it once on init_site(). (But it's not clear to me how we'd then convert that info into files that we could serve locally)
<html>
<head>
$for(css)$
<link rel="stylesheet" href="$css$" type="text/css" />
$endfor$
$for(header-includes)$
$header-includes$
$endfor$
$if(math)$
$if(mathjax)$
<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script>
$endif$
$math$
$endif$
</head>
</html>
(But it's not clear to me how we'd then convert that info into files that we could serve locally)
Depending on whether we further pursue https://github.com/r-lib/pkgdown/pull/2249, we could just leverage assemble_ext_assets() to do this. It would only require small modifications to https://github.com/r-lib/pkgdown/pull/2249 to also handle the dynamically determined mathjax/katex assets.
But I'm not sure whether it's worth to determine the mathjax/katex asset versions used by Pandoc defaults dynamically at pkgdown site build-time in the first place. Instead we could also just hardcode the (currently) latest versions in assets_external.yaml and simply update them from time to time (which would arrive to users via new pkgdown releases).
@salim-b ah yeah, that's a good strategy. We can code up the approach I outline above, and then use it once per release to update the external assets yaml.
@hadley We could do that. Or we could just define the latest asset versions in assets_external.yaml and update them independently of Pandoc. The CDN URLs Pandoc uses as default fallback aren't updated very often, it seems (e.g. katex v0.15.1 that Pandoc still uses was released on 2021-10-31; latest is v0.16.10 from 2024-03-24).
@salim-b I like the idea of keeping in sync with pandoc as that gives one fewer difference from rmarkdown etc.
Next Pandoc release will use the latest KaTeX CDN asset: https://github.com/jgm/pandoc/pull/9707 ☺️
Update: Pandoc v3.2 just got released incl. mentioned PR
Post #2263, also need to apply to convert_markdown_to_html(). And that implies that any description can now contain mathjax, hence the mathjax header deps need to be set on every page (not just articles/rmd).
@salim-b I think you're beginning to convince me — it does seem overwrought to go through all this work just to capture two urls that don't change very often.
Where should the math-rendering option go in _pkgdown.yml? Under template? I'm thinking e.g.
template:
math-rendering: katex
We'd default to mathml since that minimises dependencies and most sites don't use that much math; and sites that do want better rendering can use mathjax or katex.
Where should the math-rendering option go in
_pkgdown.yml? Undertemplate?
Yep, template.math-rendering seems the right place to me, too.
We'd default to mathml since that minimises dependencies and most sites don't use that much math
I think that is sensible. 👍