Document a font fix for plotmath expressions under ragg (#2913)

Author: remlapmot

NEWS.md

@@ -2,6 +2,8 @@
 
 * `build_site()` gained a `quiet` argument, which is propagated to other functions
   (e.g., `build_articles()`) and is useful for debugging build errors on GH actions.
+* Added documentation explaining how to solve incorrect rendering of plotmath expressions under ragg devices on Linux. (@remlapmot, #2908)
+* Improved the LaTeX syntax in one of the math rendering test cases (@remlapmot)
 
 # pkgdown 2.1.3
 

R/test.R

@@ -287,8 +287,8 @@ NULL
 #'
 #' Multi-line equation (correctly rendered by katex only):
 #'
-#' \deqn{\mathit{Minimize} \space l \\
-#' \mathit{subject \space to} \\
+#' \deqn{\text{Minimize } l \\
+#' \text{ subject 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}{

man/test-math-examples.Rd

@@ -235,6 +235,21 @@ template:
   math-rendering: katex
 ```
 
+On Linux the default symbol font is _Standard Symbols PS_. Unfortunately, this font does not render plotmath expressions correctly under pkgdown's default graphics device `ragg::png`. There are several simple solutions to this:
+
+* Before building your site, use the systemfonts package to change the symbol font to one which does render plotmath expressions correctly under ragg such as _Liberation Sans_, e.g.: 
+  
+  ```r
+  systemfonts::register_variant("symbol", "Liberation Sans")
+  ```
+
+* Configure pkgdown to use R's `grDevices::png` device by specifying the following in `_pkgdown.yml`:
+
+  ```yaml
+  figures:
+    dev: grDevices::png
+  ```
+
 ### Navbar style
 
 When [light-switch](#light-switch) is disabled, the primary navbar colours are determined by HTML classes, not CSS, and can be customized using the `navbar` fields `bg` and `type` which control the background and foreground colours respectively.