fix: improve support for math rendering with CDN

[jayhesselberth]

This PR includes katex and mathjax dependencies via the head template instead of via cached_dependency().

This simplifies the katex loading, which otherwise would require caching ~60 katex files.

But once katex material moved to the head template, then it doesn't make sense to have a separate approach for mathjax, so that is moved to the head template too.

Closes #2704

[github-actions]

🚀 Deployed on https://67c46654f3485755f397ecaf--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]

The only other thing I would do here is to add an example using mathml directly for testing purposes, ideally something that can't be used by katex and mathjax