Improve support for math rendering with CDN

NEWS.md

@@ -1,5 +1,7 @@
 # pkgdown (development version)
 
+* Support for math rendering using katex and mathjax was improved and now includes necessary components using CDN (#2704).
+* Articles (i.e., Rmarkdown/Quarto documents in `vignettes/articles`, created by `usethis::use_article()` and available on pkgdown sites but not included in a built package) have improved test cases (thanks to @venpopov and @ethanbass).
 * pkgdown now uses the same Sass variables as bslib to set the navbar background color: `$navbar-bg` for the background color in light and dark mode, or `$navbar-light-bg` and `$navbar-dark-bg` for individually controlling light and dark mode background colors. `pkgdown-navbar-bg` and `$pkgdown-navbar-bg-dark` both still provide pkgdown-specific overrides (@gadenbuie, #2847).
 * Code repositories hosted on Codeberg are now supported in the `BugReports` and `URL` fields (@nfrerebeau, #2843).
 * Articles (i.e., vignettes in `vignettes/articles`, created by `usethis::use_article()` and available on pkgdown sites but not included in a built package) have improved test cases (thanks to @venpopov and @ethanbass).

R/external-deps.R

@@ -70,21 +70,6 @@ math_dependency <- function(pkg, call = caller_env()) {
         )
       )
     )
-  } else if (math == "katex") {
-    cached_dependency(
-      name = "KaTex",
-      version = "0.16.10",
-      files = list(
-        list(
-          url = "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js",
-          integrity = "sha384-hIoBPJpTUs74ddyc4bFZSM1TVlQDA60VBbJS0oA934VSz82sBx1X7kSx2ATBDIyd"
-        ),
-        list(
-          url = "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css",
-          integrity = "sha384-wcIxkf4k558AjM3Yz3BBFQUbk/zgIYC2R0QpeeYb+TwlBVMrlgLqwRjRtGZiK7ww"
-        )
-      )
-    )
   } else {
     NULL
   }
@@ -136,7 +121,7 @@ compute_hash <- function(path, size) {
   con <- file(path, encoding = "UTF-8")
   openssl::base64_encode(openssl::sha2(con, size))
 }
- 
+
 parse_integrity <- function(x) {
   size <- as.integer(regmatches(x, regexpr("(?<=^sha)\\d{3}", x, perl = TRUE)))
   hash <- regmatches(x, regexpr("(?<=^sha\\d{3}-).+", x, perl = TRUE))

R/markdown.R

@@ -109,6 +109,7 @@ convert_markdown_to_html <- function(pkg, in_path, out_path, ...) {
       cli::cli_abort("Pandoc not available")
     }
   }
+
   rmarkdown::pandoc_convert(
     input = in_path,
     output = out_path,

R/render.R

@@ -128,6 +128,7 @@ data_template <- function(pkg = ".", depth = 0L) {
   out$footer <- data_footer(pkg)
   out$lightswitch <- uses_lightswitch(pkg)
   out$uses_katex <- config_math_rendering(pkg) == "katex"
+  out$uses_mathjax <- config_math_rendering(pkg) == "mathjax"
 
   print_yaml(out)
 }

R/test.R

@@ -285,6 +285,18 @@ NULL
 #'
 #' \deqn{y = \alpha + \beta X + \varepsilon}
 #'
+#' Multi-line equation (correctly rendered by katex only):
+#'
+#' \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}
+#'
 #' @name test-math-examples
 #' @keywords internal
 #' @family tests

inst/BS5/templates/head.html

@@ -12,8 +12,26 @@
 <link rel="manifest" href="{{#site}}{{root}}{{/site}}site.webmanifest">
 {{/has_favicons}}
 
+{{#uses_katex}}
+<!-- katex math -->
+<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>
+<script src="{{#site}}{{root}}{{/site}}katex-auto.js"></script>
+{{/uses_katex}}
+
+{{#uses_mathjax}}
+<!-- mathjax math fonts -->
+<script>
+  window.MathJax = {
+    chtml: {
+      fontURL: "https://cdn.jsdelivr.net/npm/[email protected]/es5/output/chtml/fonts/woff-v2"
+    }
+  };
+</script>
+{{/uses_mathjax}}
+
 {{#lightswitch}}<script src="{{#site}}{{root}}{{/site}}lightswitch.js"></script>{{/lightswitch}}
-{{#uses_katex}}<script src="{{#site}}{{root}}{{/site}}katex-auto.js"></script>{{/uses_katex}}
 
 {{{headdeps}}}
 {{#includes}}{{{head}}}{{/includes}}

tests/testthat/_snaps/render.md

@@ -49,6 +49,7 @@
       right: <p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> {version}.</p>
     lightswitch: no
     uses_katex: no
+    uses_mathjax: no
 
 
 # check_opengraph validates inputs

tests/testthat/test-build-article.R

@@ -141,7 +141,7 @@ test_that("can control math mode", {
   expect_equal(xpath_length(html, ".//span[contains(@class, 'math')]"), 1)
   expect_contains(
     path_file(xpath_attr(html, ".//script", "src")),
-    c("katex-auto.js", "katex.min.js")
+    c("katex-auto.js", "auto-render.min.js", "katex.min.js")
   )
 })
 

vignettes/customise.Rmd

@@ -226,7 +226,7 @@ template:
 
 ### Math rendering
 
-By default, pkgdown will render math using mathml. mathml is the official standard for rendering math on the web, and requires no additional javascript or css dependencies. However, browser support for complex math is not always that good, so if you are including complex equations in your documentation, you may want to switch to either [`katex`](https://katex.org) or [`mathjax`](https://www.mathjax.org) by using the `template.math-rendering` field:
+By default, pkgdown will render math using [mathml](https://w3c.github.io/mathml/). mathml is the official standard for rendering math on the web, and requires no additional javascript or css dependencies. However, browser support for complex math is not always that good, so if you are including complex equations in your documentation, you may want to switch to either [`katex`](https://katex.org), which we recommend for display of complex math expressions, or [`mathjax`](https://www.mathjax.org) by using the `template.math-rendering` field:
 
 ```yaml
 template: