Introduction to gridmicrotex

Aligning to the math baseline

In addition to numeric justifications in [0, 1], hjust and vjust also accept named values. The most useful one is vjust = "baseline", which places the formula’s math baseline (not the bbox centre) on the anchor point — so a formula sits next to surrounding text the way it would in a typeset document.

grid::grid.newpage()
y <- 0.5
grid::grid.segments(unit(0, "npc"), unit(y, "npc"),
                    unit(1, "npc"), unit(y, "npc"),
                    gp = grid::gpar(col = "grey80"))
grid::grid.text("if ", x = 0.10, y = y, just = c(0, 0.5),
                gp = grid::gpar(fontsize = 16))
grid.latex("$x \\geq \\sqrt{2\\pi}$",
           x = 0.22, y = y,
           hjust = "left", vjust = "baseline",
           gp = grid::gpar(fontsize = 16))
grid::grid.text(", then proceed.", x = 0.62, y = y, just = c(0, 0.5),
                gp = grid::gpar(fontsize = 16))

hjust accepts "left"/"bbleft", "center"/"centre"/"middle"/ "bbcentre", and "right"/"bbright". vjust accepts "bottom", "center"/"centre"/"middle", "top", and "baseline".

Named anchors with \mark{}

The \mark{name} macro records a named anchor at its position inside the formula. grobMark() then resolves the anchor to a pair of grid units, ready to drive an arrow, callout, or any other grob.

A mark works at any nesting level — between top-level tokens, on a compound sub-expression like b^2, even inside a superscript or fraction. The position inherits the surrounding transform (font shrink for scripts, scaling, rotation), so the anchor lands on the rendered glyph rather than a pre-layout offset.

g <- latex_grob(
  r"($a^2 + b\mark{term}^2 \mark{equals}= c^2$)",
  x = 0.5, y = 0.4,
  gp = grid::gpar(fontsize = 28)
)
grid::grid.newpage()
grid::grid.draw(g)

# Callout 1: the "=" sign, pointed at from above.
mk_eq <- grobMark(g, "equals")
grid::grid.segments(mk_eq$x, mk_eq$y + unit(15, "mm"),
                    mk_eq$x, mk_eq$y + unit(3, "mm"),
                    arrow = grid::arrow(length = unit(2, "mm"), type = "closed"),
                    gp = grid::gpar(col = "red"))
grid::grid.text("equals", x = mk_eq$x, y = mk_eq$y + unit(18, "mm"),
                gp = grid::gpar(col = "red", fontsize = 11))

# Callout 2: the b^2 term, pointed at from below — the mark sits at the
# end of the term, including the superscript's smaller scale.
mk_bsq <- grobMark(g, "term")
grid::grid.segments(mk_bsq$x - unit(6, "mm"), mk_bsq$y - unit(15, "mm"),
                    mk_bsq$x - unit(2, "mm"), mk_bsq$y - unit(3, "mm"),
                    arrow = grid::arrow(length = unit(2, "mm"), type = "closed"),
                    gp = grid::gpar(col = "blue"))
grid::grid.text("b² term",
                x = mk_bsq$x - unit(7, "mm"),
                y = mk_bsq$y - unit(18, "mm"),
                just = "right",
                gp = grid::gpar(col = "blue", fontsize = 11))

Because the returned units carry the grob’s viewport position and hjust/vjust, you can pass them straight to grid.points, grid.segments, or any other grid drawing function — no manual offset arithmetic.

\mark records a single point, not a span. To centre a callout over a multi-glyph term, place the mark at the term’s end and shift in your drawing code, or place a pair of marks (\mark{l}…\mark{r}) and use their midpoint.

Advanced: loading custom fonts

Use load_font() to add any additional OpenType math font. The OpenType MATH table is parsed directly in C++ — no companion metrics file or external toolchain is required:

load_font("path/to/MyFont.otf")

Render modes

gridmicrotex supports two rendering modes for math glyphs:

• "typeface" (default): Renders glyphs as native text using the math font’s typeface. This produces selectable, searchable, and accessible text in PDF and SVG output. Bundled math fonts (Lete Sans Math, STIX Two Math) and any registered via load_font() are read directly from their OTF files — no system-wide font install is required. Requires a device that supports the R 4.3 glyph engine (e.g., ragg::agg_png(), svglite::svglite(), grDevices::cairo_pdf()). On devices that do not (e.g., the base pdf() device), the package automatically falls back to path mode with a warning.

• "path": Renders each glyph as a filled vector path. This works on all R graphics devices and produces pixel-perfect output. However, text in PDF/SVG output is not selectable or searchable.

# Default typeface mode (selectable text in PDF/SVG)
grid.latex("E = mc^2", gp = grid::gpar(fontsize = 24))

# Explicit path mode (works everywhere, but text is not selectable)
grid.latex("E = mc^2", gp = grid::gpar(fontsize = 24), render_mode = "path")

Important: Do not use showtext::showtext_auto() with typeface mode. The showtext package globally intercepts all text rendering and converts it to vector paths. This silently defeats typeface mode, causing all math glyphs to appear as paths instead of native text — even on devices like svglite and ragg that fully support font embedding. If you need showtext for other parts of your plot, disable it before drawing LaTeX formulas:

showtext::showtext_auto(FALSE)
grid.latex("E = mc^2", gp = grid::gpar(fontsize = 24))  # typeface mode works correctly

Font pairing

The bundled math fonts have different styles. For a consistent look, pair them with a matching fontfamily:

grid::grid.newpage()
grid.latex(
  "\\text{Theorem: } \\forall x \\in \\mathbb{R},\\; x^2 \\geq 0",
  math_font = "stix",
  gp = grid::gpar(fontfamily = "serif", fontsize = 12)
)

Complicated examples

grid::grid.newpage()
grid.latex(paste0(
      "\\begin{array}{l}",
      "  \\forall\\varepsilon\\in\\mathbb{R}_+^*\\ \\exists\\eta>0",
      "\\ |x-x_0|\\leq\\eta\\Longrightarrow|f(x)-f(x_0)|\\leq\\varepsilon\\\\",
      "  \\det",
      "  \\begin{bmatrix}",
      "      a_{11}&a_{12}&\\cdots&a_{1n}\\\\",
      "      a_{21}&\\ddots&&\\vdots\\\\",
      "      \\vdots&&\\ddots&\\vdots\\\\",
      "      a_{n1}&\\cdots&\\cdots&a_{nn}",
      "  \\end{bmatrix}",
      "  \\overset{\\mathrm{def}}{=}\\sum_{\\sigma\\in\\mathfrak{S}_n}",
      "\\varepsilon(\\sigma)\\prod_{k=1}^n a_{k\\sigma(k)}\\\\",
      "  \\int_0^\\infty{x^{2n} e^{-a x^2}\\,dx} = \\frac{2n-1}{2a}",
      " \\int_0^\\infty{x^{2(n-1)} e^{-a x^2}\\,dx}",
      " = \\frac{(2n-1)!!}{2^{n+1}} \\sqrt{\\frac{\\pi}{a^{2n+1}}}\\\\",
      "\\end{array}"
), gp = grid::gpar(fontsize = 16))

grid::grid.newpage()

grid.latex(
  "
  \\newcolumntype{s}{>{\\color{#1234B6}}c}
\\begin{array}{|c|c|c|s|}
  \\hline
  \\rowcolor{Tan}\\multicolumn{4}{|c|}{\\textcolor{white}{\\bold{\\text{Table Head}}}}\\\\
  \\hline
  \\text{Matrix}&\\multicolumn{2}{|c|}{\\text{Multicolumns}}&\\text{Font size commands}\\\\
  \\hline
  \\begin{pmatrix}
      \\alpha_{11}&\\cdots&\\alpha_{1n}\\\\
      \\hdotsfor{3}\\\\
      \\alpha_{n1}&\\cdots&\\alpha_{nn}
  \\end{pmatrix}
  &\\large \\text{Left}&\\cellcolor{#00bde5}\\small \\textcolor{white}{\\text{\\bold{Right}}}
  &\\small \\text{small Small}\\\\
  \\hline
  \\multicolumn{4}{|c|}{\\text{Table Foot}}\\\\
  \\hline
\\end{array}
  ",
  gp = grid::gpar(fontsize = 22)
)

grid::grid.newpage()
grid.latex(
  "\\definecolor{gris}{gray}{0.9}
\\definecolor{noir}{rgb}{0,0,0}
\\definecolor{bleu}{rgb}{0,0,1}
\\fatalIfCmdConflict{false}
\\newcommand{\\pa}{\\left|}
\\begin{array}{c}
  \\LaTeX\\\\
  \\begin{split}
      |I_2| &= \\pa\\int_0^T\\psi(t)\\left\\{ u(a,t)-\\int_{\\gamma(t)}^a \\frac{d\\theta}{k} (\\theta,t) \\int_a^\\theta c(\\xi)
          u_t (\\xi,t)\\,d\\xi\\right\\}dt\\right|\\\\
      &\\le C_6 \\Bigg|\\pa f \\int_\\Omega \\pa\\widetilde{S}^{-1,0}_{a,-}
          W_2(\\Omega, \\Gamma_1)\\right|\\ \\right|\\left| |u|\\overset{\\circ}{\\to} W_2^{\\widetilde{A}}(\\Omega\\Gamma_r,T)\\right|\\Bigg|\\\\
      &\\\\
      &\\begin{pmatrix}
          \\alpha&\\beta&\\gamma&\\delta\\\\
          \\aleph&\\beth&\\gimel&\\daleth\\\\
          \\mathfrak{A}&\\mathfrak{B}&\\mathfrak{C}&\\mathfrak{D}\\\\
          \\boldsymbol{\\mathfrak{a}}&\\boldsymbol{\\mathfrak{b}}&\\boldsymbol{\\mathfrak{c}}&\\boldsymbol{\\mathfrak{d}}
      \\end{pmatrix}
      \\quad{(a+b)}^{\\frac{n}{2}}=\\sqrt{\\sum_{k=0}^n\\tbinom{n}{k}a^kb^{n-k}}\\quad
          \\Biggl(\\biggl(\\Bigl(\\bigl(()\\bigr)\\Bigr)\\biggr)\\Biggr)\\\\
      &\\forall\\varepsilon\\in\\mathbb{R}_+^*\\ \\exists\\eta>0\\ |x-x_0|\\leq\\eta\\Longrightarrow|f(x)-f(x_0)|\\leq\\varepsilon\\\\
      &\\det
      \\begin{bmatrix}
          a_{11}&a_{12}&\\cdots&a_{1n}\\\\
          a_{21}&\\ddots&&\\vdots\\\\
          \\vdots&&\\ddots&\\vdots\\\\
          a_{n1}&\\cdots&\\cdots&a_{nn}
      \\end{bmatrix}
      \\overset{\\mathrm{def}}{=}\\sum_{\\sigma\\in\\mathfrak{S}_n}\\varepsilon(\\sigma)\\prod_{k=1}^n a_{k\\sigma(k)}\\\\
      &\\Delta f(x,y)=\\frac{\\partial^2f}{\\partial x^2}+\\frac{\\partial^2f}{\\partial y^2}\\qquad\\qquad \\fcolorbox{noir}{gris}
          {n!\\underset{n\\rightarrow+\\infty}{\\sim} {\\left(\\frac{n}{e}\\right)}^n\\sqrt{2\\pi n}}\\\\
      &\\sideset{_\\alpha^\\beta}{_\\gamma^\\delta}{
      \\begin{pmatrix}
          a&b\\\\
          c&d
      \\end{pmatrix}}
      \\xrightarrow[T]{n\\pm i-j}\\sideset{^t}{}A\\xleftarrow{\\overrightarrow{u}\\wedge\\overrightarrow{v}}
          \\underleftrightarrow{\\iint_{\\mathds{R}^2}e^{-\\left(x^2+y^2\\right)}\\,\\mathrm{d}x\\mathrm{d}y}
  \\end{split}\\\\
  \\rotatebox{30}{\\sum_{n=1}^{+\\infty}}\\quad\\mbox{Mirror rorriM}\\reflectbox{\\mbox{Mirror rorriM}}
\\end{array}",
  gp = grid::gpar(fontsize = 22),
  render_mode = "path"
)

Lists

The itemize and enumerate environments lay their items out as a left-aligned column, one item per row — itemize prefixes each item with a bullet, enumerate numbers them:

grid::grid.newpage()
grid.latex(paste0(
  "\\begin{enumerate}",
  "  \\item e^{i\\pi} + 1 = 0",
  "  \\item \\begin{itemize}",
  "           \\item \\alpha \\item \\beta",
  "         \\end{itemize}",
  "\\end{enumerate}"
), gp = grid::gpar(fontsize = 20))

An optional […] argument customises the marker. For itemize it is the literal marker (\begin{itemize}[\star]); for enumerate it is a counter template containing one of \arabic*, \alph*, \Alph*, \roman*, or \Roman* (e.g. \begin{enumerate}[\Roman*.]). Lists may nest, and an item may contain any math — including a \begin{array} table.

Because MicroTeX is a math engine, each item is typeset as a math-mode, single-line expression: there is no paragraph flow or line wrapping, and prose inside an item must be wrapped in \text{} (e.g. \item \text{First point}). The description environment is not supported.

Pasting LaTeX from other sources

When the input is generated by tools that emit complete LaTeX — for example R packages that produce ready-to-compile tabular snippets, or LaTeX fragments copy-pasted from a .tex file — the formula often arrives wrapped in document-level constructs that MicroTeX does not implement. Rather than refusing such input, gridmicrotex rewrites or removes a small set of well-known wrappers before parsing.

Removed silently (no visual effect):

Rewritten to a MicroTeX equivalent:

A note on \caption: in real LaTeX, captions are repositioned by the float machinery (typically above or below the surrounding tabular, independent of source order). Here the caption renders exactly where it appears in the source. For tools that place \caption after \end{tabular}, this gives a caption-below-table layout; for tools that place it before, you get caption-above.

A note on the skips and fills: real LaTeX defines \smallskip / \medskip / \bigskip as absolute pt amounts (3 / 6 / 12). The mapping above uses em-relative values instead, so the gap stays visible whether gp$fontsize is 10 or 30. If you need an exact absolute size, use \vspace{Xpt} directly — MicroTeX accepts pt, em, ex, mm, cm.

\hfill and \vfill are rubber lengths in LaTeX — they expand to fill the surrounding glue. A fixed-size grob has nothing to “fill,” so the mapping produces a static 1em gap. The position is right; the elasticity is gone.

Not honored (rendered as literal text, which is intentional — it makes unsupported markup easy to spot):

• Declarative font scopes: \bfseries, \itshape, \ttfamily, \sffamily, \rmfamily. These affect text within their group in LaTeX, which requires scope tracking we do not implement. Use the argument-bearing forms instead: \textbf{…}, \textit{…}, \texttt{…}, \textsf{…}, \textrm{…}, all of which MicroTeX supports natively.
• Hyperlinks and references: \url{…}, \href{…}{…}, \ref{…}, \cite{…}. There is no link concept inside a grob.
• Footnotes: \footnote{…} (positioning machinery is page-bound).
• Small caps: \textsc{…} (MicroTeX has no small-caps glyphs).

What is not supported

MicroTeX is a math formula renderer, not a full LaTeX engine. The following are outside its scope and would need a real document compiler:

• Document structure: \section, page layout, headers/footers, \tableofcontents
• Package loading semantics: \usepackage{…} is accepted but loads nothing — supported commands are all built into MicroTeX
• Paragraph text: line breaking, hyphenation, justified paragraphs
• TikZ / PGF drawing commands
• Images: \includegraphics
• Cross-references: targets via \label are silently dropped; \ref, \cite, bibliographies have nothing to resolve against
• Theorem environments: \begin{theorem}, \begin{proof}
• The description list environment (itemize and enumerate are supported — see Lists above)
• Some amsmath commands: \tag and equation numbering

For most statistical graphics use cases — axis labels, annotations, legends, and in-plot formulas — the supported feature set is more than sufficient.