% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/markdown-box.R
\name{markdown_box_grob}
\alias{markdown_box_grob}
\title{Render a markdown document as a boxed grid grob}
\usage{
markdown_box_grob(
  md,
  x = grid::unit(0.5, "npc"),
  y = grid::unit(0.5, "npc"),
  width = grid::unit(1, "npc"),
  height = NULL,
  hjust = 0.5,
  vjust = 0.5,
  halign = 0,
  valign = 1,
  padding = NULL,
  margin = NULL,
  box_gp = NULL,
  r = NULL,
  style = NULL,
  name = NULL,
  gp = grid::gpar(),
  vp = NULL
)
}
\arguments{
\item{md}{Character string of markdown.}

\item{x, y}{Position of the box in the parent viewport.}

\item{width}{Width of the box, including \code{margin}. \code{NULL}
sizes the box to its content, so nothing wraps --- useful where the
available width is not known, as in a ggplot2 theme element.}

\item{height}{Fixed height, or \code{NULL} (default) to take whatever
height the content needs.}

\item{hjust, vjust}{Justification of the whole box about \code{x} and
\code{y}.}

\item{halign}{Horizontal alignment of blocks within the box:
\code{0} left (default), \code{0.5} centred, \code{1} right.}

\item{valign}{Vertical alignment of the content when \code{height}
leaves room to spare: \code{1} top (default), \code{0} bottom.}

\item{padding, margin}{A \code{\link[grid]{unit}} of length 1 or 4
giving top, right, bottom and left. Padding is inside the box,
margin outside it. \code{NULL} (default) takes them from the
stylesheet's \code{body} rule, and is zero if that says nothing.}

\item{box_gp}{Graphical parameters for the box itself, e.g.
\code{gpar(fill = "grey95", col = "black")}. \code{NULL} (default)
takes the fill from \code{body \{ background \}} and the border from
\code{body \{ border \}}, and draws no box if neither is set.}

\item{r}{Corner radius; a non-zero value draws a rounded box.
\code{NULL} (default) takes it from \code{body \{ border-radius \}}.}

\item{style}{Appearance of the blocks: a \code{\link{markdown_style}}
object, CSS text, or a path to a \code{.css} file. \code{NULL}
(default) uses \code{latex_options("markdown_style")} if set, and
the built-in defaults otherwise.}

\item{name}{Optional grob name.}

\item{gp}{Graphical parameters for the text. \code{fontsize} also sets
the scale for block spacing and list indentation, and \code{cex}
multiplies it as elsewhere in \pkg{grid}.}

\item{vp}{Optional viewport. Supplying one replaces the viewport built
from \code{x}, \code{y}, \code{width}, \code{height}, \code{hjust}
and \code{vjust}, so those are then ignored.}
}
\value{
A \code{markdownbox} gTree.
}
\description{
Lays markdown out as a block document --- headings, paragraphs, lists
(including GFM task lists), block quotes, code blocks, tables,
horizontal rules and images --- inside an optional padded, filled and
bordered box. Prose wraps to the requested width, and \code{$...$}
math is typeset by MicroTeX as usual. All the inline formatting
\code{\link{markdown_grob}} understands, including the inline HTML
subset, works inside every block.
}
\details{
Where \code{\link{markdown_grob}} flattens everything into a single
run, this stacks one grob per block. That is what makes headings, list
indentation, block-quote rules and background fills possible:
MicroTeX has no concept of any of them, and its line breaking does not
reach inside the cells it uses for list and table layout.

Two consequences worth knowing. Table cells and code lines are not
wrapped, so a wide table overflows rather than reflowing. And list
items are stacked here rather than handed to MicroTeX's
\code{itemize}, which is what gives them a proper hanging indent.

An image on a line of its own is drawn as a raster, scaled to fit the
column but never enlarged past its natural size (pixels are read at
96 dpi). PNG needs the \pkg{png} package and JPEG needs \pkg{jpeg},
both \emph{Suggests}: when the reader is not installed, the file is
missing, or the format is anything else, the image degrades to its alt
text. An image \emph{within} a sentence stays inline, where only its
alt text survives.

The layout is computed at draw time, so an open device is required ---
which is what lets a relative \code{width} and the measured height of
the text resolve against the viewport the box is actually drawn in.
}
\section{Styling}{

Appearance comes from a small CSS cascade. \code{style} sets the house
style for the whole document, by tag:

\preformatted{markdown_box_grob(md, style = markdown_style(
  h1         = md_style(color = "steelblue", font_size = 2),
  blockquote = md_style(border_left = "3px solid grey60")
))}

The same thing written as CSS, which \code{style} also takes directly,
as text or as the path to a \code{.css} file:

\preformatted{markdown_box_grob(md, style = "
  h1 \{ color: steelblue; font-size: 2rem \}
  blockquote \{ border-left: 3px solid grey60 \}
")}

To style one chunk rather than every block of a kind, wrap it in a
\code{<div>} carrying a \code{class} or a \code{style}. \strong{Leave
blank lines around the tags} --- that is what makes CommonMark parse
the markdown between them instead of treating the whole thing as raw
HTML:

\preformatted{<div class="note">

## This heading only

</div>}

Inline runs take \code{class} as well as \code{style} on a
\code{<span>}. See \code{\link{markdown_style}} for the tag names, the
supported properties and how the cascade resolves.
}

\examples{
\donttest{
  md <- paste(
    "# Results", "",
    "The slope is $\\\\beta_1$ with *p* < 0.001.", "",
    "- first point", "- second point",
    sep = "\n"
  )
  grid::grid.newpage()
  grid::grid.draw(markdown_box_grob(
    md,
    width = grid::unit(4, "in"),
    padding = grid::unit(8, "pt"),
    box_gp = grid::gpar(fill = "grey95", col = "grey40")
  ))
}
}
\seealso{
\code{\link{markdown_grob}}, \code{\link{latex_grob}}
}
