pkgdown 2.1.0 prevents `\eqn{}` and `\deqn{}` math rendering on function reference pages under Bootstrap 5

[nanxstats]

Minimal reproducible example

#' Example
#'
#' @param x \eqn{f(x) > 0}: inline equation
#'
#' @details
#' Display equation:
#'
#' \deqn{y = \alpha + \beta X + \varepsilon}
#'
#' @export
f <- function(x) NULL

and set

template:
  bootstrap: 5

in _pkgdown.yml.

pkgdown 2.1.0 + Bootstrap 5

Expand screenshot

pkgdown 2.0.9 + Bootstrap 5

Expand screenshot

[hadley]

Hmmm, I wonder what's different between your example and https://pkgdown.r-lib.org/articles/test/rendering.html#math

...

Oh maybe because it's an example, and we don't seem to have a test for math rendering in examples :(

[cgiachalis]

@nanxstats Did you try setting the previous default, e.g. mathjax. That's solved my problem at least.

template:
  bootstrap: 5
  math-rendering: mathjax

[jayhesselberth]

Confirmed, setting math-rendering: mathjax fixes this issue.

We should try to figure out why mathml (which is now the default) doesn't work.

[cgiachalis]

Just to mention that the rendering is not what is used to be. I see different fonts as reported in #2739.

Right clicking on the equation -> About MathJax, I get the following:

Current version

Before v2.1.0

[cgiachalis]

And the answer is here: https://docs.mathjax.org/en/latest/upgrading/v2.html#not-yet-ported-to-version-3

The MathJax v3 output jax currently only support one font, the MathJax TeX fonts. Improved font support is an important goal for version 3, and this is one of the next features to be addressed. We will be rebuilding the fonts used for MathJax, and making additional web fonts available in a future release. We also plan to make the tools used for creating the necessary font data available for use in porting your own fonts for use with MathJax.

So by upgrading mathjax to v3.2.2, we don't get web TeX fonts..

[nanxstats]

This is how math rendering looks like using math-rendering: "mathjax" under pkgdown 2.1.0 (reproduced under both macOS and Windows):

Expand screenshot

Maybe it's because the MathJaX fonts are missing, from all the 404s in network requests:

Expand screenshot

---

Since it's tricky to side-load the MathJax fonts (originally defined in JS), my current workaround is to use the katex option and side-load the KaTeX fonts (also missing from pkgdown) using pkgdown/extra.css. Example: https://github.com/keaven/gsDesign/pull/161

I'm not in a place to suggest anything on the font situation, but it would be very useful to have math rendering working again on function reference pages for all engine types.

[jayhesselberth]

@nanxstats Do you know if there is a CDN source for katex / Mathjax fonts? If so we could include them in the dependencies:

https://github.com/r-lib/pkgdown/blob/1d40a80e6b3564a6d7da0ce467b0a4570aa5665e/R/external-deps.R#L60-L91

We're probably not going to bundle math fonts in pkgdown itself.

[cgiachalis]

Indeed, katex option didn't work either out of the box.

Thanks for confirming @nanxstats .

[jayhesselberth]

Would we expect inclusion of these fonts from cdnjs to have an effect? These could be added to the mathjax dependencies. There are also SVG fonts, not sure which we'd need.

It's also a little puzzling why katex fonts aren't included in the dependencies we are already listing. I can't find a reference to need a separate katex font download.

[nanxstats]

@jayhesselberth I will let the MathJax experts comment on what should be used.

For KaTeX, I think you can add these 60 fonts files as "cached dependency" (may not look pretty...). It didn't work before probably because the CSS file is cached locally and distributed with the pkgdown site. It contains relative font paths that are interpreted as the pkgdown site instead of the CDN site.

[jayhesselberth]

If we're going to need to include many external font dependencies for katex / mathjax, we may need to go back to the yaml format that was originally in #2249.

[louisaslett]

I've hit this issue just now, and felt it was a bit much work to include all the font files manually although that was a cool solution given above. My slightly hacky approach is just to remove the math-rendering: katex completely and inject the official KaTeX starter template headers directly, which uses the CDN for everything:

template:
  bootstrap: 5
  includes:
    in_header: |
      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
      <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>
      <script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

I found this "just worked" for now thankfully, though it'd be really nice to have this fixed (ideally with option not to use CDN) so that the math-rendering: katex is all we need.

[MLopez-Ibanez]

A math-heavy example that used to work until recently: https://mlopez-ibanez.github.io/eaf/reference/igd.html

[jeffreyhanson]

Just in case this is useful or if anyone else runs into this issue, I noticed that using math-rendering: mathjax doesn't seem to entirely work for multi-line equations. For example, here's a multi-line equation and how it renders in Google Chrome for me.

#' \deqn{\mathit{Minimize} \space l \\
#' \mathit{subject \space to} \\
#' \sum_{i = 1}^{I} x_i r_{ij} + y_j \geq t_j \forall j \in J \\
#' l \geq \frac{y_j}{t_j} \forall j \in J \\
#' \sum_{i = 1}^{I} x_i c_i \leq B}{
#' Minimize l subject to
#' sum_i^I (xi * rij) + yj >= tj for all j in J &
#' l >= (yj / tj) for all j in J &
#' sum_i^I (xi * ci) <= B}

As we can see, all of the equations appear on the same line, instead of appearing on separate lines (per pkgdown 2.0.9).

[jayhesselberth]

Thoughts after having played around with this issue for a bit.

1. Most pkgdown users don't need math support at all (surveying packages on github).
2. Those that need math support need good math support, and mathml doesn't cut it.
3. The current approach in pkgdown for getting katex doesn't work, I think it's a JS issue. So this needs to be fixed.
4. The katex solution proposed above works well. But katex requires a lot files from CDN and it doesn't seem like it's worth putting all of them in pkgdown itself.
5. The newest version of Mathjax (3.x) seems less capable (or more strict) than the previous (2.x). I don't know of any specific examples where mathjax would be used over katex.

I propose we just inject the katex headers from (https://github.com/r-lib/pkgdown/issues/2704#issuecomment-2307055568) when math-rendering: katex is specified.

We could also consider just dropping mathml and mathjax support as they don't appear that useful? I.e., just support one good math library, and make it opt-in.

[aitap]

Part of the problem with math-rendering: mathml and \eqn{} tags could be due to Pandoc ignoring the \eqn{} tags converted to Markdown.

The as_html method for \eqn tags outputs \( equation \): https://github.com/r-lib/pkgdown/blob/656069f523efadd27812bce6b9322a92c57eb8cb/R/rd-html.R#L130-L142

But with the current set of Markdown extensions, \(...\) is not recognised as an equation:

strace -s 1000 -v -e execve -f R -q -s -e "pkgdown::build_site('.', install = TRUE, preview = FALSE, devel = FALSE)"
# ...
# 15190 execve("/usr/bin/pandoc", ["/usr/bin/pandoc", "+RTS", "-K512m", "-RTS", "/tmp/RtmpH7omXJ/file36ce1a2a663", "--to", "html4", "--from", "markdown+gfm_auto_identifiers-citations+emoji+autolink_bare_uris", "--output", "/tmp/RtmpH7omXJ/file36ce2a01fd68", "-t", "html4", "--indented-code-classes=R", "--section-divs", "--wrap=none", "--mathml"], [ <environment omitted> ] = 0

Launching the same command manually, I see:

# using exactly the same arguments as pkgdown does
echo '\(2 \ge 1\)' | "/usr/bin/pandoc" "+RTS" "-K512m" "-RTS" "--to" "html4" "--from" "markdown+gfm_auto_identifiers-citations+emoji+autolink_bare_uris" "-t" "html4" "--indented-code-classes=R" "--section-divs" "--wrap=none" "--mathml"
# <p>(2 )</p>

# using dollar notation instead of \(...\) that pkgdown generates from \eqn{} tags
echo '$2 \ge 1$' | "/usr/bin/pandoc" "+RTS" "-K512m" "-RTS" "--to" "html4" "--from" "markdown+gfm_auto_identifiers-citations+emoji+autolink_bare_uris" "-t" "html4" "--indented-code-classes=R" "--section-divs" "--wrap=none" "--mathml"
# <p><math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>2</mn><mo>≥</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">2 \ge 1</annotation></semantics></math></p>

# enabling the additional syntax extensions
echo '\( 2 \ge 1 \)' | "/usr/bin/pandoc" "+RTS" "-K512m" "-RTS" "--to" "html4" "--from" "markdown+gfm_auto_identifiers-citations+emoji+autolink_bare_uris+tex_math_single_backslash" "-t" "html4" "--indented-code-classes=R" "--section-divs" "--wrap=none" "--mathml"
# <p><math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>2</mn><mo>≥</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">2 \ge 1</annotation></semantics></math></p>

Not sure how to fix it without breaking anything else, but it seems that maybe as_html should output equations wrapped in dollars, or Pandoc should have more syntax extensions enabled.