r-lib · jayhesselberth · Dec 20, 2024 · Dec 20, 2024
diff --git a/NEWS.md b/NEWS.md
@@ -1,6 +1,7 @@
 # pkgdown (development version)
 
-* 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).
+* Support for math rendering using katex (`math-rendering: katex`) 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).
 * New `clean_site(force = TRUE)` for cleaning of `docs/` regardless of whether it was built by pkgdown (#2827).
 * Links to favicons in page headers were updated to reflect changes to https://realfavicongenerator.net/ (#2804). Favicons should be re-generated by manually removing the `pkgdown/favicon` directory and then running `pkgdown::build_favicons()`.
 * Reinstate Rd macro loading, which was accidentally disabled in v2.1.1 (#2782).

diff --git a/R/external-deps.R b/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))

diff --git a/R/markdown.R b/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,
@@ -120,7 +121,12 @@ convert_markdown_to_html <- function(pkg, in_path, out_path, ...) {
       "--indented-code-classes=R",
       "--section-divs",
       "--wrap=none",
-      paste0("--", config_math_rendering(pkg)),
+      ifelse(
+        # katex is handled separately
+        config_math_rendering(pkg) == "katex",
+        "",
+        paste0("--", config_math_rendering(pkg))
+      ),
       ...
     ))
   )

diff --git a/R/test.R b/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

diff --git a/inst/BS5/assets/katex-auto.js b/inst/BS5/assets/katex-auto.js
diff --git a/inst/BS5/templates/head.html b/inst/BS5/templates/head.html
@@ -12,8 +12,14 @@
 <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>
+{{/uses_katex}}
+
 {{#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}}

diff --git a/man/test-math-examples.Rd b/man/test-math-examples.Rd
diff --git a/tests/testthat/_snaps/init.md b/tests/testthat/_snaps/init.md
@@ -4,7 +4,6 @@
       init_site(pkg)
     Message
       -- Initialising site -----------------------------------------------------------
-      Copying <pkgdown>/BS5/assets/katex-auto.js to katex-auto.js
       Copying <pkgdown>/BS5/assets/lightswitch.js to lightswitch.js
       Copying <pkgdown>/BS5/assets/link.svg to link.svg
       Copying <pkgdown>/BS5/assets/pkgdown.js to pkgdown.js

diff --git a/tests/testthat/test-build-article.R b/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("auto-render.min.js", "katex.min.js")
   )
 })
 

diff --git a/vignettes/customise.Rmd b/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: