% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/knit_include.R
\name{knit_include}
\alias{knit_include}
\title{Include an HTML-renderable object in any knitr output format}
\usage{
knit_include(
  x,
  file = tempfile("ki_", tmpdir = "."),
  width = 700,
  height = 400,
  ...
)
}
\arguments{
\item{x}{Any R object. Specialised handling for \code{gt_tbl} and
\code{htmlwidget}; all other classes are passed through
unchanged.}

\item{file}{Base filename (no extension) for temporary files written when
output is not HTML.  Defaults to a session-unique temp file in
the current directory so multiple calls don't collide.}

\item{width}{Viewport / screenshot width in pixels (non-HTML only).}

\item{height}{Viewport / screenshot height in pixels (non-HTML only).}

\item{...}{Additional arguments forwarded to \code{\link[gt]{gtsave}} or
\code{\link[webshot2]{webshot}}.}
}
\value{
For \code{gt_tbl} / \code{htmlwidget} in non-HTML output: the result
of \code{\link[knitr]{include_graphics}}. Otherwise: \code{x}
unchanged.
}
\description{
A pipe-friendly helper in Rmarkdown, Quarto, and other documents for objects that render natively in HTML output
(RStudio Viewer, HTML documents) but need a convenient image fallback for PDF, Word,
and other non-HTML formats. It was designed to solve a problem in rendering the result of \code{color_table()},
and then generalized to provide for other similar cases.
}
\details{
Supported classes (handled internally) solve this problem by saving the image to a file and then inserting it in the document
using \code{knitr::include_graphics()}:
\itemize{
\item \code{"gt_tbl"}     (gt package)       -- saved via \code{\link[gt]{gtsave}}
\item \code{"htmlwidget"} (htmlwidgets family: plotly, DT, leaflet, dygraphs, ...)
-- saved via
\code{\link[htmlwidgets]{saveWidget}}
+ \code{\link[webshot2]{webshot}}
}

Packages that handle cross-format output natively (\pkg{flextable}, \pkg{kableExtra},
\pkg{huxtable}) do NOT need this helper.

For any other class, \code{x} is returned as-is in all output formats and
knitr's normal printing applies.  This means the function is safe to use in
a pipe on any object: it only intervenes when it knows how to help!
}
\examples{
\dontrun{
data(HairEyeColor)
HEC <- margin.table(HairEyeColor, 1:2)

## gt_tbl from color_table()
color_table(HEC, title = "Hair x Eye Color") |> knit_include()

## DT htmlwidget
DT::datatable(mtcars) |> knit_include(width = 900, height = 500)

## plotly htmlwidget
plotly::plot_ly(mtcars, x = ~wt, y = ~mpg) |> knit_include()

## Any other object passes through unchanged
lm(mpg ~ wt, data = mtcars) |> knit_include()
}

}
