Build articles sectionSource:
build_articles() renders each R Markdown file underneath
saves it to
articles/. There are two exceptions:
Files that start with
_index.Rmd) are ignored, enabling the use of child documents in bookdown
vignettes/tutorialsare handled by
Vignettes are rendered using a special document format that reconciles
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
build_articles() directly (outside of
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.
Path to package.
FALSEto display output of knitr and pandoc. This is useful when debugging.
TRUE, will only re-build article if input file has been modified more recently than the output file.
An optional named list used to temporarily override values in
is.na(preview) && interactive(), will preview freshly generated section in browser.
Name of article to render. This should be either a path relative to
vignettes/without extension, or
Additional data to pass on to template.
Index and navbar
You can control the articles index and navbar with a
articles field in
_pkgdown.yml. If you use it, pkgdown will check that all articles
are included, and will error if you have missed any.
articles field defines a list of sections, each of which
can contain four fields:
title(required): title of section, which appears as a heading on the articles index.
desc(optional): An optional markdown description displayed underneath the section title.
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.
contents(required): a list of article names to include in the section. This can either be names of individual vignettes or a call to
starts_with(). The name of a vignette includes its path under
vignetteswithout extension so that the name of the vignette found at
The title and description of individual vignettes displayed on the index
description fields of the YAML header in the Rmds.
For example, this yaml might be used for some version of dplyr:
articles: - title: Main verbs navbar: ~ contents: - one-table - two-table - rowwise - colwise - title: Developer desc: Vignettes aimed at package developers contents: - programming - packages
Note the use of the
navbar: ~ means that the "Main verbs"
will appear in the navbar without a heading; the absence of the
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.
Note that a vignette with the same name as the package (e.g.,
becomes a top-level "Get started" link, and will not appear in the articles
(If your package name includes a
pack.down, use a
- in the
vignette name, e.g.
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
.install_extras. pkgdown takes a different approach based on
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
resource_files field to the yaml metadata, e.g.:
--- title: My Document resource_files: - data/mydata.csv - images/figure.png ---
Note that you can not use the
fig.path to change the output directory of
generated figures as its default value is a strong assumption of rmarkdown.
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. https://www.shinyapps.io). Then, you
can embed the app into your article using an
<iframe src = "https://gallery.shinyapps.io/083-front-page" class="shiny-app">.
See https://github.com/r-lib/pkgdown/issues/838#issuecomment-430473856 for some hints on how to customise the appearance with CSS.
By default, pkgdown builds all articles using the
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
as_is field in your
pkgdown: as_is: true
If the output format produces a PDF, you'll also need to specify the
pkgdown: as_is: true extension: pdf
To work with pkgdown, the output format must accept
self_contained arguments, and must work without any additional CSS or
JSS files. Note that if you use
you'll still need to add
as_is: true to each individual vignette.
Additionally, htmlwidgets do not work when
If you want articles that are not vignettes, either put them in
subdirectories or list in
.Rbuildignore. 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
You can control the default rendering of figures by specifying the
_pkgdown.yml. The default settings are equivalent to:
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: 
Most of these parameters are interpreted similarly to knitr chunk
other.parameters is a list of parameters
that will be available to custom graphics output devices such
as HTML widgets.