% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggplot2-markdown.R
\name{element_markdown}
\alias{element_markdown}
\title{A ggplot2 theme element for markdown text}
\usage{
element_markdown(
  math_font = "",
  fontsize = NULL,
  lineheight = 1.2,
  max_width = 0,
  render_mode = c("typeface", "path"),
  justify = FALSE,
  style = NA,
  width = NA,
  ...
)
}
\arguments{
\item{math_font}{Name of the math font to use (e.g. \code{"stix"}).}

\item{fontsize}{Convenience alias for \code{size}; forwarded to
\code{ggplot2::element_text()} as the text size in points.
\code{NULL} (default) uses the theme's inherited size.}

\item{lineheight}{Multi-line height multiplier (default 1.2).}

\item{max_width}{Maximum width in big points for automatic line
wrapping (default: 0, no wrapping).}

\item{render_mode}{\code{"typeface"} (default) or \code{"path"}.}

\item{justify}{Logical; justify wrapped lines. Requires
\code{max_width}.}

\item{style}{A \code{\link{markdown_style}} object, CSS text, or the
path to a \code{.css} file, applied to labels drawn through this
theme element. \code{NA}, the default, means unset --- the global
\code{\link{latex_options}(markdown_style = )} applies instead. Only
the properties that compile to LaTeX have an effect, unless the label
is laid out as blocks (see \emph{Block labels}). See
\code{\link{md_style}}.}

\item{width}{Wrapping measure for the label, as a
\code{\link[grid]{unit}}. \code{NA}, the default, means unset: the
label is sized to its content and does not wrap.
\code{unit(1, "npc")} is the useful value for a plot title, whose
cell really is the full plot width. See \emph{Block labels}.}

\item{...}{Additional arguments passed to
\code{ggplot2::element_text()} (e.g. \code{colour}, \code{hjust}).}
}
\value{
An S7 object of class \code{element_markdown}, inheriting from
\code{ggplot2::element_text}.
}
\description{
Use as a theme element for axis titles, axis labels, plot titles or any
other text element. The label is parsed as markdown --- including
\code{$...$} math --- and rendered via MicroTeX.
}
\details{
This is an S7 subclass of \code{ggplot2::element_text}, so it inherits
the standard text properties (size, colour, hjust, ...) from the theme
and merges correctly with inherited theme entries.
}
\section{Block labels}{

A label with real block structure --- a heading, a list, a table, a
rule, or more than one paragraph --- is laid out by
\code{\link{markdown_box_grob}} rather than flattened into one run, so
list markers, indents and block spacing survive. That makes a title
like this work:

\preformatted{labs(title = "## Findings\\n\\n- slope $\\\\beta_1$\\n- *p* < 0.001")}

The box's own background, border, padding and corner radius come from
the stylesheet's \code{body} rule --- \code{style = "body \{ background:
grey95; padding: 8px \}"} --- not from arguments here. See
\code{\link{markdown_style}}.

Three details follow from how ggplot2 measures theme elements:

\itemize{
\item \strong{Wrapping is opt-in.} Without \code{width} the label is
sized to its content, because ggplot2 asks an element for its
height before placing it, when a relative width would resolve
against the whole device rather than the element's cell.
\item \strong{Axis tick labels are never laid out as blocks},
whatever they contain, for the same reason.
\item \strong{A rotated label is never laid out as blocks.} The box
cannot rotate, so a label with both blocks and a non-zero
\code{angle} keeps the angle, is rendered as a single run, and
warns. A \code{width} given with an angle becomes the run's
wrapping measure instead.
}

\code{math_font}, \code{render_mode} and \code{justify} are not
forwarded to the box; a block label takes those from
\code{\link{latex_options}}.

Note that \pkg{ggtext} also exports a function called
\code{element_markdown()}. If both packages are attached, the one loaded
later wins; call \code{gridmicrotex::element_markdown()} explicitly to
be unambiguous. The two are not interchangeable --- ggtext renders
HTML/CSS and images, this renders LaTeX math.
}

\examples{
\donttest{
if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  ggplot(mtcars, aes(wt, mpg)) + geom_point() +
    labs(x = "**weight** in $10^3$ lbs") +
    theme(axis.title.x = gridmicrotex::element_markdown())
}
}
}
\seealso{
\code{\link{markdown_grob}}, \code{\link{element_latex}}
}
