🚀 Deployed on https://67c46654f3485755f397ecaf--pkgdown-dev.netlify.app

@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.

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:

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.

@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.

@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✨

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/[email protected]/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.

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

I have no more comments.

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