build_articles.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-articles.R, R/build-article.R
\name{build_articles}
\alias{build_articles}
\alias{build_article}
\alias{build_articles_index}
\title{Build articles section}
\usage{
build_articles(
  pkg = ".",
  quiet = TRUE,
  lazy = TRUE,
  seed = 1014L,
  n_cores = 1L,
  override = list(),
  preview = FALSE
)

build_article(
  name,
  pkg = ".",
  lazy = FALSE,
  seed = 1014L,
  new_process = TRUE,
  pandoc_args = character(),
  override = list(),
  quiet = TRUE
)

build_articles_index(pkg = ".", override = list())
}
\arguments{
\item{pkg}{Path to package.}

\item{quiet}{Set to \code{FALSE} to display output of knitr and
pandoc. This is useful when debugging.}

\item{lazy}{If \code{TRUE}, will only re-build article if input file has been
modified more recently than the output file.}

\item{seed}{Seed used to initialize random number generation in order to
make article output reproducible. An integer scalar or \code{NULL} for no seed.}

\item{n_cores}{Number of workers to use when building articles in
parallel. A positive integer (fractional values are rounded up), or
\code{Inf} to use \code{parallel::detectCores()}. Defaults to \code{1L}, which keeps
the traditional serial build and does not require the \pkg{mirai}
package. Values greater than 1 require \pkg{mirai} and use
\code{\link[purrr:in_parallel]{purrr::in_parallel()}}.}

\item{override}{An optional named list used to temporarily override
values in \verb{_pkgdown.yml}}

\item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview
freshly generated section in browser.}

\item{name}{Name of article to render. This should be either a path
relative to \verb{vignettes/} \emph{without extension}, or \code{index} or \code{README}.}

\item{new_process}{Build the article in a clean R process? The default,
\code{TRUE}, ensures that every article is build in a fresh environment, but
you may want to set it to \code{FALSE} to make debugging easier.}

\item{pandoc_args}{Pass additional arguments to pandoc. Used for testing.}
}
\description{
\code{build_articles()} renders each R Markdown file underneath \verb{vignettes/} and
saves it to \verb{articles/}. There are two exceptions:
\itemize{
\item Files that start with \verb{_} (e.g., \verb{_index.Rmd}) are ignored,
enabling the use of child documents.
\item Files in \code{vignettes/tutorials} are handled by \code{\link[=build_tutorials]{build_tutorials()}}
}

Vignettes are rendered using a special document format that reconciles
\code{\link[rmarkdown:html_document]{rmarkdown::html_document()}} with the pkgdown template. This means articles
behave slightly differently to vignettes, particularly with respect to
external files, and custom output formats. See below for more details.

Note that when you run \code{build_articles()} directly (outside of
\code{\link[=build_site]{build_site()}}) vignettes will use the currently installed version of the
package, not the current source version. This makes iteration quicker when
you are primarily working on the text of an article.
}
\section{Index and navbar}{
You can control the articles index and navbar with a \code{articles} field in
your \verb{_pkgdown.yml}. If you use it, pkgdown will check that all articles
are included, and will error if you have missed any.

The \code{articles} field defines a list of sections, each of which
can contain four fields:
\itemize{
\item \code{title} (required): title of section, which appears as a heading on the
articles index.
\item \code{desc} (optional): An optional markdown description displayed underneath
the section title.
\item \code{navbar} (optional): A couple of words used to label this section in
the navbar. If omitted, this section of vignettes will not appear in the
navbar.
\item \code{contents} (required): a list of article names to include in the
section. This can either be names of individual vignettes or a
call to \code{starts_with()}. The name of a vignette includes its
path under \code{vignettes} without extension so that the name of the vignette
found at \code{vignettes/pizza/slice.Rmd} is \code{pizza/slice}.
}

The title and description of individual vignettes displayed on the index
comes from \code{title} and \code{description} fields of the YAML header in the Rmds.

For example, this yaml might be used for some version of dplyr:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{articles:
- title: Main verbs
  navbar: ~
  contents:
  - one-table
  - two-table
  - rowwise
  - colwise

- title: Developer
  desc: Vignettes aimed at package developers
  contents:
  - programming
  - packages
}\if{html}{\out{</div>}}

Note the use of the \code{navbar} fields. \verb{navbar: ~} means that the "Main verbs"
will appear in the navbar without a heading; the absence of the \code{navbar}
field in the developer vignettes means that they will only be
accessible via the articles index.

The navbar will include a link to the articles index if one or more
vignettes are not available through the navbar. If some vignettes appear
in the navbar drop-down list and others do not, the list will automatically
include a "More ..." link at the bottom; if no vignettes appear in the
the navbar, it will link directly to the articles index instead of
providing a drop-down.
\subsection{Get started}{

Note that a vignette with the same name as the package (e.g.,
\code{vignettes/pkgdown.Rmd} or \code{vignettes/articles/pkgdown.Rmd}) automatically
becomes a top-level "Get started" link, and will not appear in the articles
drop-down.

(If your package name includes a \code{.}, e.g. \code{pack.down}, use a \code{-} in the
vignette name, e.g. \code{pack-down.Rmd}.)
}

\subsection{Missing articles}{

pkgdown will warn if there are (non-internal) articles that aren't listed
in the articles index. You can suppress such warnings by listing the
affected articles in a section with \code{title: internal} (case sensitive);
this section will not be displayed on the index page.
}

\subsection{External articles}{

You can link to arbitrary additional articles by adding an
\code{external-articles} entry to \verb{_pkgdown.yml}. It should contain an array
of objects with fields \code{name}, \code{title}, \code{href}, and \code{description}.

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{external-articles:
- name: subsampling
  title: Subsampling for Class Imbalances
  description: Improve model performance in imbalanced data sets through undersampling or oversampling.
  href: https://www.tidymodels.org/learn/models/sub-sampling/
}\if{html}{\out{</div>}}

If you've defined a custom articles index, you'll need to include the name
in one of the \code{contents} fields.
}
}

\section{External files}{
pkgdown differs from base R in its handling of external files. When building
vignettes, R assumes that vignettes are self-contained (a reasonable
assumption when most vignettes were PDFs) and only copies files explicitly
listed in \code{.install_extras}. pkgdown takes a different approach based on
\code{\link[rmarkdown:find_external_resources]{rmarkdown::find_external_resources()}}, and it will also copy any images that
you link to. If for some reason the automatic detection doesn't work, you
will need to add a \code{resource_files} field to the yaml metadata, e.g.:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{---
title: My Document
resource_files:
  - data/mydata.csv
  - images/figure.png
---
}\if{html}{\out{</div>}}

Note that you can not use the \code{fig.path} to change the output directory of
generated figures as its default value is a strong assumption of rmarkdown.
}

\section{Embedding Shiny apps}{
If you would like to embed a Shiny app into an article, the app will have
to be hosted independently, (e.g. \url{https://www.shinyapps.io}). Then, you
can embed the app into your article using an \verb{<iframe>}, e.g.
\verb{<iframe src = "https://gallery.shinyapps.io/083-front-page" class="shiny-app">}.

See \url{https://github.com/r-lib/pkgdown/issues/838#issuecomment-430473856} for
some hints on how to customise the appearance with CSS.
}

\section{Output formats}{
By default, pkgdown builds all articles using the
\code{\link[rmarkdown:html_document]{rmarkdown::html_document()}} \code{output} format, ignoring whatever is set in
your YAML metadata. This is necessary because pkgdown has to integrate the
HTML/CSS/JS from the vignette with the HTML/CSS/JS from rest of the site.
Because of the challenges of combining two sources of HTML/CSS/JS, there is
limited support for other output formats and you have to opt-in by setting
the \code{as_is} field in your \code{.Rmd} metadata:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{pkgdown:
  as_is: true
}\if{html}{\out{</div>}}

If the output format produces a PDF, you'll also need to specify the
\code{extension} field:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{pkgdown:
  as_is: true
  extension: pdf
}\if{html}{\out{</div>}}

To work with pkgdown, the output format must accept \code{template}, \code{theme}, and
\code{self_contained} arguments, and must work without any additional CSS or
JSS files. Note that if you use
\href{https://bookdown.org/yihui/rmarkdown/html-document.html#shared-options}{\verb{_output.yml}}
or \href{https://rmarkdown.rstudio.com/docs/reference/render_site.html}{\verb{_site.yml}}
you'll still need to add \code{as_is: true} to each individual vignette.

Additionally, htmlwidgets do not work when \code{as_is: true}.
}

\section{Suppressing vignettes}{
If you want \href{https://r-pkgs.org/vignettes.html#sec-vignettes-article}{articles}
that are not vignettes, use \code{usethis::use_article()} to create it. An articles link will be
automatically added to the default navbar if the vignettes directory is
present: if you do not want this, you will need to customise the navbar. See
\code{\link[=build_site]{build_site()}} details.
}

\section{Figures}{
You can control the default rendering of figures by specifying the \code{figures}
field in \verb{_pkgdown.yml}. The default settings are equivalent to:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{figures:
  dev: ragg::agg_png
  dpi: 96
  dev.args: []
  fig.ext: png
  fig.width: 7.2916667
  fig.height: ~
  fig.retina: 2
  fig.asp: 1.618
  bg: NA
  other.parameters: []
}\if{html}{\out{</div>}}

Most of these parameters are interpreted similarly to knitr chunk
options. \code{other.parameters} is a list of parameters
that will be available to custom graphics output devices such
as HTML widgets.
}

\seealso{
Other site components: 
\code{\link{build_home}()},
\code{\link{build_llm_docs}()},
\code{\link{build_news}()},
\code{\link{build_reference}()},
\code{\link{build_tutorials}()}
}
\concept{site components}