Improve support for math rendering with CDN

[jayhesselberth]

Closes #2704

[github-actions]

🚀 Deployed on https://677c24c179adcf10df488e2d--pkgdown-dev.netlify.app

[jayhesselberth]

@hadley I think the CDN approach for katex is the best we're going to do. We'd have to cache ~60 files to fully support katex outside of CDN.

[nanxstats]

Thanks @jayhesselberth for this fix. I ran some manual tests on this branch across different math-rendering options in _pkgdown.yml (under bootstrap: 5). Below are the current results:

math-rendering	Function reference	Articles	Notes
"mathml" (default)	Unrendered	Renders	Inconsistent behavior
"katex"	Renders	Unrendered	Inconsistent behavior
"mathjax"	Renders	Renders	MathJaX web fonts didn't load - suboptimal appearance

[jayhesselberth]

Articles need katex-auto.js to render correctly.

The complex math example (test-math-examples) doesn't render correctly in the netlify preview because we don't set math-rendering: katex in this PR.

[jayhesselberth]

@nanxstats Can you confirm this fixes katex for you?

What do you mean by "function reference" in the table above — math included in params and examples? I'm not sure why mathml is not rendering that correctly.

[nanxstats]

@jayhesselberth Yes, "function reference" means the function documentation pages under reference/, where math is written with the \eqn{} \deqn{} syntax.

Overall results

Here is how it looks after the latest patch - KaTeX is now ✨perfect✨

math-rendering	Function reference	Articles	Notes
"mathml" (default)	Unrendered	Renders	Inconsistent behavior
"katex"	Renders	Renders	Perfect
"mathjax"	Renders	Renders	MathJaX web fonts didn't load - suboptimal appearance

Load MathJaX web fonts

You can configure MathJaX via the fontURL JS option to load fonts from CDN like below, similar to the KaTeX method.

In R/render.R, after the out$uses_katex line, add:

out$uses_mathjax <- config_math_rendering(pkg) == "mathjax"

In inst/BS5/templates/head.html, after the {{#uses_katex}} block, add the following {{#uses_mathjax}} block:

{{#uses_mathjax}}
<script>
  window.MathJax = {
      chtml: {
          fontURL: "https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/output/chtml/fonts/woff-v2"
      }
  };
</script>
{{/uses_mathjax}}

On MathML

Yep, under mathml, math on function reference pages is not parsed as math at all, indicating any fix is probably more involved. I won't use the mathml option because it will likely render something suboptimal when any serious math is involved, so not fixing mathml is not a blocker.

I do support considering KaTeX as the future default, like you mentioned in #2704.

[nanxstats]

Nice, I can confirm MathJax now also loads web fonts properly:

math-rendering	Function reference	Articles	Notes
"mathml" (default)	❌	✅	Inconsistent behavior, maybe for future fix
"katex"	✅	✅	Perfect
"mathjax"	✅	✅	Perfect

I have no more comments.

[jayhesselberth]

If we're moving to supporting math libraries with CDN, then we should move MathJax from the cached libraries and into the head template:

pkgdown/R/external-deps.R

Lines 62 to 72 in 4519ca0

	if (math == "mathjax") {
	cached_dependency(
	name = "MathJax",
	version = "3.2.2",
	files = list(
	list(
	url = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-chtml.min.js",
	integrity = "sha512-T8xxpazDtODy3WOP/c6hvQI2O9UPdARlDWE0CvH1Cfqc0TXZF6GZcEKL7tIR8VbfS/7s/J6C+VOqrD6hIo++vQ=="
	)
	)
	)