Math rendering with `bookdown::html_document2` and `pkgdown::build_articles`

[athowes]

Hi,

I'm having trouble getting math to render correctly for an R package website built using pkgdown.

I'm writing vignettes with the following options:

output: 
  bookdown::html_document2:
    fig_caption: yes
    number_sections: yes

When template.math-rendering is mathml then equations display incorrectly on the rendered website as follows:

Alternatively, with template.math-rendering as mathjax then equations do display but in a strange font (this is how the website is currently):

Here is my session information:

> sessionInfo()
R version 4.4.1 (2024-06-14)
Platform: aarch64-apple-darwin20
Running under: macOS Sonoma 14.5

Matrix products: default
BLAS:   /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: Europe/London
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] helios_0.1.0

loaded via a namespace (and not attached):
 [1] gtable_0.3.5       xfun_0.45          bslib_0.7.0        ggplot2_3.5.1      httr2_1.0.2       
 [6] htmlwidgets_1.6.4  devtools_2.4.5     remotes_2.5.0      processx_3.8.4     callr_3.7.6       
[11] generics_0.1.3     vctrs_0.6.5        tools_4.4.1        ps_1.7.7           curl_5.2.1        
[16] tibble_3.2.1       fansi_1.0.6        pkgconfig_2.0.3    desc_1.4.3         gt_0.10.1         
[21] individual_0.1.16  lifecycle_1.0.4    compiler_4.4.1     stringr_1.5.1      tictoc_1.2.1      
[26] munsell_0.5.1      fontawesome_0.5.2  httpuv_1.6.15      htmltools_0.5.8.1  usethis_2.2.3     
[31] sass_0.4.9         yaml_2.3.9         tidyr_1.3.1        later_1.3.2        pillar_1.9.0      
[36] pkgdown_2.1.0.9000 jquerylib_0.1.4    urlchecker_1.0.1   whisker_0.4.1      ellipsis_0.3.2    
[41] cachem_1.1.0       sessioninfo_1.2.2  mime_0.12          tidyselect_1.2.1   digest_0.6.36     
[46] stringi_1.8.4      dplyr_1.1.4        purrr_1.0.2        bookdown_0.40.1    forcats_1.0.0     
[51] rprojroot_2.0.4    cowplot_1.1.3      fastmap_1.2.0      grid_4.4.1         here_1.0.1        
[56] colorspace_2.1-0   cli_3.6.3          magrittr_2.0.3     pkgbuild_1.4.4     utf8_1.2.4        
[61] withr_3.0.0        scales_1.3.0       promises_1.3.0     rappdirs_0.3.3     rmarkdown_2.27    
[66] memoise_2.0.1      shiny_1.8.1.1      evaluate_0.24.0    knitr_1.48         miniUI_0.1.1.1    
[71] profvis_0.3.8      rlang_1.1.4        downlit_0.4.4      Rcpp_1.0.12        xtable_1.8-4      
[76] glue_1.7.0         xml2_1.3.6         pkgload_1.4.0      rstudioapi_0.16.0  jsonlite_1.8.8    
[81] R6_2.5.1           fs_1.6.4   

Any help appreciated, thanks!

[jayhesselberth]

Do you know if your rendering worked in the last version of pkgdown (2.0.9)?

This may be a dup of #2734

[athowes]

Yes, on reversion to pkgdown version 2.0.9. it works.

[Bisaloo]

We had the same issue when setting pkgdown.as_is: true in the vignettes, as I see you are doing in some vignettes.

What happens is that pkgdown uses mathml by default since 2.1.0, when bookdown uses mathjax. pkgdown.as_is: true will convert the markdown to mathjax-ready HTML but the mathjax library is no longer loaded by pkgdown.

You have a couple of options to fix this:

• remove pkgdown.as_is: true but that may break some bookdown specific settings that pkgdown doesn't support
• add math_method: mathml in the relevant vignettes under the html_vignette2 format options
• revert the math rendering engine to mathjax in the pkgdown options

[hadley]

Another option (which will have substantial benefits in the long term) is to convert vignettes that use bookdown::html_document2 to quarto, since that will get you back on the fully supported path. (But we should try to fix this buglet regardless).