Should it be easier to not load MathJax/to tweak the version? #1966

maelle · 2021-12-13T11:52:36Z

At the moment to not have MathJax or to load a different version one needs to override the head.html template.

Should it be easier to not include MathJax? E.g. providing an opt-out.

From looking at https://github.com/r-lib/pkgdown/blob/main/inst/BS5/templates/head.html, I see no other element that's loaded everywhere but not useful everywhere.

I know this was discussed following #1566 but without the aspect that one can't choose another version.

Cc @jeroen

jeroen · 2021-12-13T12:49:50Z

I think ideally we be able to specify a mathjax_version in overrides, and also be able to set it to false for no mathjax.

hadley · 2021-12-13T15:22:02Z

Are there that many differences between mathjax versions?

jeroen · 2021-12-14T08:13:48Z

I think it's mostly just faster: https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html
Perhaps it doesn't work as well on some very old browsers.

hadley · 2021-12-14T13:22:14Z

So why do more than updating mathjax in pkgdown? That seems like it would be easier?

jeroen · 2021-12-14T13:36:41Z

It's still very heavy and only used by a handful of packages, we prefer to make it opt-in for rOpenSci. But we can make this work by shipping a custom head.html in our template, so not super important.

salim-b · 2022-12-05T17:50:52Z

There are two commits from an abandoned PR branch that might be helpful when updating MathJax to v3: 39f001e and 63af614

The tex-mml-chtml MathJax 3.1.2 component is used there (which of course is outdated meanwhile).

EliHolmes-NOAA · 2023-06-09T23:05:52Z

Are there that many differences between mathjax versions?

FYI Yes version 3.0 has completely different configuration than version 2.0. For example, the MathJax configuration java-script that you use to turn on equation numbers is completely different between the two versions.

hadley · 2024-04-24T17:15:13Z

Should we switch from mathjax to mathml? It looks like it's well supported by all major browsers (https://caniuse.com/mathml), and it would eliminate an external dependency.

(We could default to mathml, but still allow folks to switch back to the previous mathjax approach if mathml didn't work for them)

jeroen · 2024-04-24T17:28:16Z

I mathjax is needed to convert latex to mathml? If you want something in R, katex::katex_mathml() or katex::katex_html allow you to eliminate the browser-side javascript dependencies, see the vignette

hadley · 2024-04-24T18:58:07Z

Is there some reason not to use pandoc's mathml conversion? https://pandoc.org/MANUAL.html#math-rendering-in-html

hadley · 2024-04-24T19:01:33Z

@Bisaloo looks like maybe you have some experience with this?

salim-b · 2024-04-24T19:22:59Z

Is there some reason not to use pandoc's mathml conversion? https://pandoc.org/MANUAL.html#math-rendering-in-html

I guess it would absolutely make sense to use Pandoc for this. If we rely on Pandoc for the conversion, why not give users the choice to opt in to --katex or --mathjax instead of the (new) default --mathml?

While the future appears to belong to MathML, browser support is still somewhat rudimentary compared to KaTeX/MathJax. See Pandoc's math demo pages (in your preferred browser) for a rendering quality comparison:

MathML
KaTeX
MathJax
WebTeX (raster image based, hence scaling sucks)

Another nice browser math engine comparison site: https://mk12.github.io/web-math-demo/
(last updated on Apr 14, 2022; for the used asset versions, see https://github.com/mk12/web-math-demo/blob/main/index.html#L99-L119)

hadley · 2024-04-24T19:41:48Z

The main reason not to expose more math rendering options is that it's potentially a bunch of work that few people would benefit from.

Bisaloo · 2024-04-25T12:45:33Z

@Bisaloo looks like maybe you have some experience with this?

No sorry, I don't know enough to help with this

hadley · 2024-04-25T17:57:07Z

Looks like we'll need to use some basic markdown file with a custom template (see below) in order to extract the version of mathjax that pandoc uses. If we're doing that, then it does probably make sense to support at least katex, since we'd need to do the same thing. We could capture this info in a similar way to build_bslib(), doing it once on init_site(). (But it's not clear to me how we'd then convert that info into files that we could serve locally)

<html>
<head>
$for(css)$
  <link rel="stylesheet" href="$css$" type="text/css" />
$endfor$
$for(header-includes)$
  $header-includes$
$endfor$
$if(math)$
$if(mathjax)$
  <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script>
$endif$
  $math$
$endif$
</head>
</html>

salim-b · 2024-04-25T22:46:15Z

(But it's not clear to me how we'd then convert that info into files that we could serve locally)

Depending on whether we further pursue #2249, we could just leverage assemble_ext_assets() to do this. It would only require small modifications to #2249 to also handle the dynamically determined mathjax/katex assets.

But I'm not sure whether it's worth to determine the mathjax/katex asset versions used by Pandoc defaults dynamically at pkgdown site build-time in the first place. Instead we could also just hardcode the (currently) latest versions in assets_external.yaml and simply update them from time to time (which would arrive to users via new pkgdown releases).

hadley · 2024-04-28T22:06:34Z

@salim-b ah yeah, that's a good strategy. We can code up the approach I outline above, and then use it once per release to update the external assets yaml.

salim-b · 2024-04-29T10:16:12Z

@hadley We could do that. Or we could just define the latest asset versions in assets_external.yaml and update them independently of Pandoc. The CDN URLs Pandoc uses as default fallback aren't updated very often, it seems (e.g. katex v0.15.1 that Pandoc still uses was released on 2021-10-31; latest is v0.16.10 from 2024-03-24).

hadley · 2024-04-29T19:23:26Z

@salim-b I like the idea of keeping in sync with pandoc as that gives one fewer difference from rmarkdown etc.

salim-b · 2024-04-29T22:44:40Z

Next Pandoc release will use the latest KaTeX CDN asset: jgm/pandoc#9707 ☺️

Update: Pandoc v3.2 just got released incl. mentioned PR

hadley · 2024-05-13T20:16:57Z

Post #2263, also need to apply to convert_markdown_to_html(). And that implies that any description can now contain mathjax, hence the mathjax header deps need to be set on every page (not just articles/rmd).

hadley · 2024-05-26T13:57:55Z

@salim-b I think you're beginning to convince me — it does seem overwrought to go through all this work just to capture two urls that don't change very often.

Where should the math-rendering option go in _pkgdown.yml? Under template? I'm thinking e.g.

template:
  math-rendering: katex

We'd default to mathml since that minimises dependencies and most sites don't use that much math; and sites that do want better rendering can use mathjax or katex.

salim-b · 2024-05-26T15:12:40Z

Where should the math-rendering option go in _pkgdown.yml? Under template?

Yep, template.math-rendering seems the right place to me, too.

We'd default to mathml since that minimises dependencies and most sites don't use that much math

I think that is sensible. 👍

Fixes #1966

Fixes r-lib#1966

maelle mentioned this issue Dec 13, 2021

override head ropensci-org/rotemplate#60

Merged

hadley added feature a feature request or enhancement front end 🌷 General HTML, CSS, and JS issues labels Jan 6, 2022

maelle mentioned this issue Jun 9, 2023

Update mathjax to version 3 or move extra.js below mathjax call? #2308

Closed

hadley added this to the 2.1.0 milestone Apr 12, 2024

hadley added a commit that referenced this issue May 29, 2024

Optionally choose math rendering

268b95d

Fixes #1966

hadley closed this as completed in 9bee264 May 30, 2024

SebKrantz pushed a commit to SebKrantz/pkgdown that referenced this issue Jun 1, 2024

Give user control over math rendering (r-lib#2599)

45bb253

Fixes r-lib#1966

bastistician mentioned this issue Sep 8, 2024

Rd math rendering is broken in pkgdown 2.1.0 #2775

Closed

kaitejohnson mentioned this issue Sep 17, 2024

fix rendering to katex, add mathcal Rt to vignette CDCgov/ww-inference-model#169

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Should it be easier to not load MathJax/to tweak the version? #1966

Should it be easier to not load MathJax/to tweak the version? #1966

maelle commented Dec 13, 2021

jeroen commented Dec 13, 2021

hadley commented Dec 13, 2021

jeroen commented Dec 14, 2021

hadley commented Dec 14, 2021

jeroen commented Dec 14, 2021 •

edited

Loading

salim-b commented Dec 5, 2022 •

edited

Loading

EliHolmes-NOAA commented Jun 9, 2023

hadley commented Apr 24, 2024 •

edited

Loading

jeroen commented Apr 24, 2024 •

edited

Loading

hadley commented Apr 24, 2024

hadley commented Apr 24, 2024

salim-b commented Apr 24, 2024 •

edited

Loading

hadley commented Apr 24, 2024

Bisaloo commented Apr 25, 2024

hadley commented Apr 25, 2024

salim-b commented Apr 25, 2024

hadley commented Apr 28, 2024

salim-b commented Apr 29, 2024

hadley commented Apr 29, 2024

salim-b commented Apr 29, 2024 •

edited

Loading

hadley commented May 13, 2024 •

edited

Loading

hadley commented May 26, 2024

salim-b commented May 26, 2024

Should it be easier to not load MathJax/to tweak the version? #1966

Should it be easier to not load MathJax/to tweak the version? #1966

Comments

maelle commented Dec 13, 2021

jeroen commented Dec 13, 2021

hadley commented Dec 13, 2021

jeroen commented Dec 14, 2021

hadley commented Dec 14, 2021

jeroen commented Dec 14, 2021 • edited Loading

salim-b commented Dec 5, 2022 • edited Loading

EliHolmes-NOAA commented Jun 9, 2023

hadley commented Apr 24, 2024 • edited Loading

jeroen commented Apr 24, 2024 • edited Loading

hadley commented Apr 24, 2024

hadley commented Apr 24, 2024

salim-b commented Apr 24, 2024 • edited Loading

hadley commented Apr 24, 2024

Bisaloo commented Apr 25, 2024

hadley commented Apr 25, 2024

salim-b commented Apr 25, 2024

hadley commented Apr 28, 2024

salim-b commented Apr 29, 2024

hadley commented Apr 29, 2024

salim-b commented Apr 29, 2024 • edited Loading

hadley commented May 13, 2024 • edited Loading

hadley commented May 26, 2024

salim-b commented May 26, 2024

jeroen commented Dec 14, 2021 •

edited

Loading

salim-b commented Dec 5, 2022 •

edited

Loading

hadley commented Apr 24, 2024 •

edited

Loading

jeroen commented Apr 24, 2024 •

edited

Loading

salim-b commented Apr 24, 2024 •

edited

Loading

salim-b commented Apr 29, 2024 •

edited

Loading

hadley commented May 13, 2024 •

edited

Loading