[bug] Equations no longer render on pkgdown website vignettes

[venpopov]

I just re-rendered the website after adding the m3 vignette (#237), and suddenly all of the articles have broken equation rendering:

Here's the in development version: https://venpopov.github.io/bmm/dev/articles/bmm_sdm_simple.html
The existing web version for the main branch is fine: https://venpopov.github.io/bmm/articles/bmm_sdm_simple.html

A quick search led me to r-lib/pkgdown#2704 This is a big problem as all our articles rely heavily on math rendering and we need to fix this before the next pkg release.

[venpopov]

r-lib/pkgdown#2704 (comment) suggests to use mathjax:

template:
  bootstrap: 5
  math-rendering: mathjax

This helps a little bit, but it's really ugly and it also dosn't render multiline equations like before:

I don't consider this a viable solution

[venpopov]

related issue: r-lib/pkgdown#2739

[venpopov]

I tried to resolve this by converting our articles to quarto articles, but then I ran into a different problem:

r-lib/pkgdown#2846

Fun times.

[venpopov]

@GidonFrischkorn rather figuring out how to fix this in the short term and then wait for quarto vignettes in pkgdown to be fully functional, I’m considering moving the artcles to a regular Quarto website, just like we did with the developer notes. We already made the decision last year to only have online vignettes and not any built in the package documentation, so we don’t loose anything really, and don’t have to deal with headaches caused by opinionated pkgdown defaults and changes and its quirks. From the user perspective nothing will change since I’ll link them to the same tab. Thoughts?

[GidonFrischkorn]

I see your point and agree that we should reduce the dependencies to pkgdown as much as possible for the time being.

The only issue I see if we spilt up too many parts of the website in different quarto websites it might also become tedious to maintain in the long run.

But for now it's fine for me. We should not have to much work moving back and forth between the options as the quarto files remain the same, right.

[venpopov]

Yeah, I thought about the issue of fragmentation and I have the same concern. Maybe consolidate everything else into one quarto website that has the articles, the devnotes and whatever else we decide to add. So just two repositories - the code (this one) and docs (articles, developer notes, simulations, etc)

[GidonFrischkorn]

This sounds good to me. Than we have the main package description as well as the function reference on the pkgdown webpage and the rest in an independent quarto webpage.

The only thing we need to look out for then is to not use math equations in the descriptions for the functions to avoid rendering issues there, right?

[venpopov]

oh. Good catch. Do we use currently any equations in function documentation? Perhaps in some of the distributions, I’ll have to check. If we do, I’d rather try one of the temporary fixes mentioned in some of threads above rather than getting rid of them. I’ll take care of it

[venpopov]

Checklist:

• Check if we have any function documentation that uses math
• Apply the custom KATEX fix suggested in one of the linked threads
• If that is sufficient, maybe skip the transition to a separte quarto site that combines vignettes and developer notes
• If not sufficient, rename the devnotes repo to something like bmm-manual and move the articles alongside the dev notes there