Jeroen Ooms

A new rOpenSci package [katex](https://cran.r-project.org/package=katex)
is now on CRAN.This package allows for converting latex math expressions
to HTML and MathML for use in markdown documents or package
documentation.

The R package uses the [katex javascript
library](https://katex.org/docs/api.html), but the rendering is done
directly in R using the V8 engine (i.e. server-side), which eliminates
the need for embedding the MathJax library into html pages.

## What it means to render server-side

To display a tex math in html we need a math typesetting library. The
standard solution is to include [MathJax](https://www.mathjax.org/) with
the html page, which attempts to convert math to html in the browser,
upon loading of the webpage.However MathJax is quite heavy, which slows
down the page, and it may not work in browsers where use of JavaScript
or external libraries is restricted.

An alternative solution is to perform the rendering when you generate
the html page, and embed the pre-generated html snippet directly in the
document. This makes the html file slightly larger, but the page loads
much faster and is more robust because we do not need a complex
dependency on the client. This is often called "server-side", because
usually html is generated by a web server.

The new katex package provides server-side math rendering in R. It can
be used to include math when generating html in R (e.g. via Rmarkdown or
R package documentation) without having to include MathJax in the output
html document.

## Tex math rendering in R

Functions
[`katex_html()`](https://docs.ropensci.org/katex/reference/katex.html)
and
[`katex_mathml()`](https://docs.ropensci.org/katex/reference/katex.html)
render a string with math to a html and mathml string. The html output
has an option `preview` which will show a preview of the generated HTML
snippet directly in a browser or the RStudio viewer.

::: {.highlight}
``` {.chroma tabindex="0"}
# Basic example: render and show math htmllibrary(katex)math <- example_math()html <- katex_html(math, preview = TRUE)# Convert to mathmlmathml <- katex_mathml(math)cat(mathml)
```
:::

![rstudio-viewer](rstudio-viewer.png)Note that by default, katex_html
actually returns a mix of HTML for visual rendering and includes MathML
for accessibility. The [katex
docs](https://docs.ropensci.org/katex/reference/katex.html) site has
more detailed information and additional options.Hopefully this can be
used to enable support for [server-side math in
knitr/rmarkdown](https://github.com/rstudio/rmarkdown/pull/1940#issuecomment-875546179)
soon!

## Embedding math in R documentation

The katex package also has a powerful helper function
[`math_to_rd`](https://docs.ropensci.org/katex/reference/math_to_rd.html)
to insert math into R documentation (`.rd`) files. This uses Katex
rendering for R documentation rendered in html format, and the
appropriate latex macros for documentation rendered in pdf or
plain-text.

You can call this directly from within your roxygen2 or Rd files using
the `\Sexpr` macro like this:

::: {.highlight}
``` {.chroma tabindex="0"}
\Sexpr[results=rd, stage=build]{  katex::math_to_rd(katex::example_math())}
```
:::

[[[$$f(x) = \frac{1}{\sigma\sqrt{2\pi}}e^{- \frac{1}{2}(\frac{x - \mu}{\sigma})^{2}}$$]{.katex-mathml}[[[]{.strut
style="height:1em;vertical-align:-0.25em;"}[f]{.mord .mathnormal
style="margin-right:0.10764em;"}[(]{.mopen}[x]{.mord
.mathnormal}[)]{.mclose}[]{.mspace
style="margin-right:0.2777777777777778em;"}[=]{.mrel}[]{.mspace
style="margin-right:0.2777777777777778em;"}]{.base}[[]{.strut
style="height:2.25144em;vertical-align:-0.93em;"}[[[]{.mopen
.nulldelimiter}[[[[[[]{.pstrut style="height:3em;"}[[σ]{.mord
.mathnormal style="margin-right:0.03588em;"}[[[[[[]{.pstrut
style="height:3em;"}[[2]{.mord}[π]{.mord .mathnormal
style="margin-right:0.03588em;"}]{.mord
style="padding-left:0.833em;"}]{.svg-align style="top:-3em;"}[[]{.pstrut
style="height:3em;"}[![](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDAwZW0iIGhlaWdodD0iMS4wOGVtIiB2aWV3Ym94PSIwIDAgNDAwMDAwIDEwODAiIHByZXNlcnZlYXNwZWN0cmF0aW89InhNaW5ZTWluIHNsaWNlIj48cGF0aCBkPSJNOTUsNzAyYy0yLjcsMCwtNy4xNywtMi43LC0xMy41LC04Yy01LjgsLTUuMywtOS41LC0xMCwtOS41LC0xNGMwLC0yLDAuMywtMy4zLDEsLTRjMS4zLC0yLjcsMjMuODMsLTIwLjcsNjcuNSwtNTRjNDQuMiwtMzMuMyw2NS44LC01MC4zLDY2LjUsLTUxYzEuMywtMS4zLDMsLTIsNSwtMmM0LjcsMCw4LjcsMy4zLDEyLDEwczE3MywzNzgsMTczLDM3OGMwLjcsMCwzNS4zLC03MSwxMDQsLTIxM2M2OC43LC0xNDIsMTM3LjUsLTI4NSwyMDYuNSwtNDI5YzY5LC0xNDQsMTA0LjUsLTIxNy43LDEwNi41LC0yMjFsMCAtMGM1LjMsLTkuMywxMiwtMTQsMjAsLTE0SDQwMDAwMHY0MEg4NDUuMjcyNHMtMjI1LjI3Miw0NjcsLTIyNS4yNzIsNDY3cy0yMzUsNDg2LC0yMzUsNDg2Yy0yLjcsNC43LC05LDcsLTE5LDdjLTYsMCwtMTAsLTEsLTEyLC0zcy0xOTQsLTQyMiwtMTk0LC00MjJzLTY1LDQ3LC02NSw0N3pNODM0IDgwaDQwMDAwMHY0MGgtNDAwMDAweiI+PC9wYXRoPjwvc3ZnPg==)]{.hide-tail
style="min-width:0.853em;height:1.08em;"}]{style="top:-2.86722em;"}]{.vlist
style="height:0.90722em;"}[​]{.vlist-s}]{.vlist-r}[[]{.vlist
style="height:0.13278em;"}]{.vlist-r}]{.vlist-t .vlist-t2}]{.mord
.sqrt}]{.mord}]{style="top:-2.2027799999999997em;"}[[]{.pstrut
style="height:3em;"}[]{.frac-line
style="border-bottom-width:0.04em;"}]{style="top:-3.23em;"}[[]{.pstrut
style="height:3em;"}[[1]{.mord}]{.mord}]{style="top:-3.677em;"}]{.vlist
style="height:1.32144em;"}[​]{.vlist-s}]{.vlist-r}[[]{.vlist
style="height:0.93em;"}]{.vlist-r}]{.vlist-t
.vlist-t2}]{.mfrac}[]{.mclose .nulldelimiter}]{.mord}]{.mord}[[e]{.mord
.mathnormal}[[[[[[]{.pstrut style="height:3em;"}[[[−]{.mord
.mtight}[[[]{.mopen .nulldelimiter .sizing .reset-size3
.size6}[[[[[[]{.pstrut style="height:3em;"}[[[2]{.mord .mtight}]{.mord
.mtight}]{.sizing .reset-size3 .size1
.mtight}]{style="top:-2.656em;"}[[]{.pstrut
style="height:3em;"}[]{.frac-line .mtight
style="border-bottom-width:0.049em;"}]{style="top:-3.2255000000000003em;"}[[]{.pstrut
style="height:3em;"}[[[1]{.mord .mtight}]{.mord .mtight}]{.sizing
.reset-size3 .size1 .mtight}]{style="top:-3.384em;"}]{.vlist
style="height:0.8443142857142858em;"}[​]{.vlist-s}]{.vlist-r}[[]{.vlist
style="height:0.344em;"}]{.vlist-r}]{.vlist-t
.vlist-t2}]{.mfrac}[]{.mclose .nulldelimiter .sizing .reset-size3
.size6}]{.mord .mtight}]{.mord .mtight}[(]{.mopen .mtight}[[]{.mopen
.nulldelimiter .sizing .reset-size3 .size6}[[[[[[]{.pstrut
style="height:3em;"}[[[σ]{.mord .mathnormal .mtight
style="margin-right:0.03588em;"}]{.mord .mtight}]{.sizing .reset-size3
.size1 .mtight}]{style="top:-2.656em;"}[[]{.pstrut
style="height:3em;"}[]{.frac-line .mtight
style="border-bottom-width:0.049em;"}]{style="top:-3.2255000000000003em;"}[[]{.pstrut
style="height:3em;"}[[[x]{.mord .mathnormal .mtight}[−]{.mbin
.mtight}[μ]{.mord .mathnormal .mtight}]{.mord .mtight}]{.sizing
.reset-size3 .size1
.mtight}]{style="top:-3.4623857142857144em;"}]{.vlist
style="height:0.87905em;"}[​]{.vlist-s}]{.vlist-r}[[]{.vlist
style="height:0.344em;"}]{.vlist-r}]{.vlist-t
.vlist-t2}]{.mfrac}[]{.mclose .nulldelimiter .sizing .reset-size3
.size6}]{.mord .mtight}[[)]{.mclose .mtight}[[[[[[]{.pstrut
style="height:2.5em;"}[[2]{.mord .mtight}]{.sizing .reset-size3 .size1
.mtight}]{style="top:-2.931em;margin-right:0.07142857142857144em;"}]{.vlist
style="height:0.8913142857142857em;"}]{.vlist-r}]{.vlist-t}]{.msupsub}]{.mclose
.mtight}]{.mord .mtight}]{.sizing .reset-size6 .size3
.mtight}]{style="top:-3.4130000000000003em;margin-right:0.05em;"}]{.vlist
style="height:1.0369199999999998em;"}]{.vlist-r}]{.vlist-t}]{.msupsub}]{.mord}]{.base}]{.katex-html
aria-hidden="true"}]{.katex}]{.katex-display}

Check out the `?math_to_rd` manual page in R or the [math_to_rd
docs](https://docs.ropensci.org/katex/reference/math_to_rd.html) for
live examples and more details.


A new rOpenSci package katex is now on CRAN.This package allows for converting latex math expressions to HTML and MathML for use in markdown documents or package documentation. The R package uses the katex javascript library, but the rendering is done directly in R using the V8 engine (i.e. server-side), which eliminates the need for embedding the MathJax library into html pages.

Messaggi di Rogue Scholar

New package katex: rendering math to HTML and MathML in R