Type: Package
Title: Rendering Math to HTML, 'MathML', or R-Documentation Format
Version: 1.5.0
Description: Convert latex math expressions to HTML and 'MathML' for use in markdown documents or package manual pages. The rendering is done in R using the V8 engine (i.e. server-side), which eliminates the need for embedding the 'MathJax' library into your web pages. In addition a 'math-to-rd' wrapper is provided to automatically render beautiful math in R documentation files.
License: MIT + file LICENSE
URL: https://docs.ropensci.org/katex/, https://github.com/ropensci/katex https://katex.org/docs/options.html (upstream)
BugReports: https://github.com/ropensci/katex/issues
Encoding: UTF-8
RoxygenNote: 7.3.2.9000
Imports: V8
VignetteBuilder: knitr
Suggests: knitr, rmarkdown
NeedsCompilation: no
Packaged: 2024-09-28 12:42:06 UTC; jeroen
Author: Jeroen Ooms ORCID iD [aut, cre], Khan Academy and other contributors [cph] (KaTeX JavaScript library)
Maintainer: Jeroen Ooms <jeroenooms@gmail.com>
Repository: CRAN
Date/Publication: 2024-09-29 09:20:02 UTC

Tex math rendering in R

Description

Converts tex-style math expressions to html and mathml for use in manual pages or markdown documents. The conversion is done in R using V8 ("server-side"), hence the resulting fragment can be inserted into an HTML document without the need for a JavaScript library like MathJax. Only the katex.css style file is required in the final html document. Use math_to_rd for embedding math into R documentation (.rd) pages.

Usage

katex_html(
  tex,
  displayMode = TRUE,
  ...,
  include_css = FALSE,
  preview = interactive()
)

katex_mathml(tex, displayMode = TRUE, ...)

example_math()

Arguments

tex

input string with tex math expression.

displayMode

render math in centered 2D layout, similar to ⁠$$⁠ in tex. Set to FALSE to render (non-centered) inline layout for use in text. For pdf output, this corresponds to the ⁠\deqn{}⁠ and ⁠\eqn{}⁠ macros, see WRE 2.6: Mathematics

...

additional html rendering options passed to katex.render

include_css

adds the katex css file to the output. This is only required once per html webpage. Set to FALSE if you include css files into the your html head some other way.

preview

open an HTML preview page showing the snipped in the browser

Details

Refer to the upstream katex support table for the full list of supported tex functions that can be rendered to html using katex.

By default, katex_html returns a mix of HTML for visual rendering and includes MathML for accessibility. To only get html, pass output="html" in the extra options, see also the katex documentation.

Value

a string with a html/mathml fragment

See Also

Other katex: math_to_rd(), pandoc

Examples

# Basic examples
html <- katex_html(example_math())
mathml <- katex_mathml(example_math())

# Example from katex.org homepage:
macros <- list("\\f" = "#1f(#2)")
math <- "\\f\\relax{x} = \\int_{-\\infty}^\\infty \\f\\hat\\xi\\,e^{2 \\pi i \\xi x} \\,d\\xi"
html <- katex_html(math,  macros = macros)
mathml <- katex_mathml(math,  macros = macros)

Display math in R documentation

Description

Helper function to insert tex math expressions into R documentation (.rd) files. Uses Katex rendering for documentation in html format, and the appropriate latex macros for documentation rendered in pdf or plain-text.

Usage

math_to_rd(tex, ascii = tex, displayMode = TRUE, ..., include_css = TRUE)

Arguments

tex

input string with tex math expression.

ascii

alternate text-only representation of the input math to show in documentation rendered to plain text format.

displayMode

render math in centered 2D layout, similar to ⁠$$⁠ in tex. Set to FALSE to render (non-centered) inline layout for use in text. For pdf output, this corresponds to the ⁠\deqn{}⁠ and ⁠\eqn{}⁠ macros, see WRE 2.6: Mathematics

...

additional html rendering options passed to katex.render

include_css

adds the katex css file to the output. This is only required once per html webpage. Set to FALSE if you include css files into the your html head some other way.

Details

Use math_to_rd() inside ⁠\Sexpr⁠ to embed math in your R package documentation pages. For example the code below can be inserted in your rd (or roxygen) source code: 

\Sexpr[results=rd, stage=build]{
  katex::math_to_rd(katex::example_math())
}

Which results in the following output:

f(x)=1σ2πe−12(x−μσ)2f(x)= {\frac{1}{\sigma\sqrt{2\pi}}}e^{- {\frac {1}{2}} (\frac {x-\mu}{\sigma})^2}

Optionally you can specify an alternate ascii representation that will be shown in the plain-text format rendering of the documentation: 

\Sexpr[results=rd, stage=build]{
  katex::math_to_rd('E=MC^2', 'E=mc²')
}
E=MC2E=MC^2

If no ascii representation is given, the input tex in displayed verbatim into the plain-text documentation.

Value

a string with an rd fragment to be included in R documentation

Note for Windows

On Windows, R versions before 4.1.2 had a bug which could lead to incorrect HTML encoding for ⁠\Sexpr{}⁠ output. As a workaround, we automatically escape non-ascii html characters on these versions of R. Linux and MacOS are unaffected.

See Also

Other katex: katex, pandoc

Renders math in HTML document

Description

Reads an html file and substitutes elements of class "math display" and "math inline" with rendered html math. This is mainly intended as a post-processing step for pandoc, which generates such html for equations. As a result the math can be displayed without the need for including the mathjax library in the html document.

Usage

render_math_in_html(
  input,
  output = NULL,
  ...,
  throwOnError = FALSE,
  include_css = TRUE
)

Arguments

input

path to the html input file

output

path to the output html file, or NULL to return as string

...

additional html rendering options passed to katex.render

throwOnError

should invalid math raise an error in R? See katex options

include_css

automatically inject the required katex css in the html head

See Also

Other katex: katex, math_to_rd()