Build articles section

build_articles() renders each R Markdown file underneath vignettes/ and saves it to articles/. There are two exceptions:

Files that start with _ (e.g., _index.Rmd) are ignored, enabling the use of child documents in bookdown
Files in vignettes/tutorials are handled by build_tutorials()

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.

build_articles(
  pkg = ".",
  quiet = TRUE,
  lazy = TRUE,
  override = list(),
  preview = NA
)

build_article(name, pkg = ".", data = list(), lazy = FALSE, quiet = TRUE)

build_articles_index(pkg = ".")

Arguments

pkg: Path to package.
quiet: Set to FALSE to display output of knitr and pandoc. This is useful when debugging.
lazy: If TRUE, will only re-build article if input file has been modified more recently than the output file.
override: An optional named list used to temporarily override values in _pkgdown.yml
preview: If TRUE, or is.na(preview) && interactive(), will preview freshly generated section in browser.
name: Name of article to render. This should be either a path relative to vignettes/ without extension, or index or README.
data: Additional data to pass on to template.

You can control the articles index and navbar with a articles section in your _pkgdown.yaml. It 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 vignettes without extension so that the name of the vignette found at vignettes/pizza/slice.Rmd is pizza/slice.

The title and description of individual vignettes displayed on the index comes from title and 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 fields. navbar: ~ means that the "Main verbs" will appear in the navbar without a heading; the absence of the 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.

Get started

Note that a vignette with the same name as the package (e.g., vignettes/pkgdown.Rmd or 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 ., e.g. pack.down, use a - in the vignette name, e.g. pack-down.Rmd.)

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 .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>, e.g. <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.

YAML header

By default, pkgdown builds all articles with rmarkdown::html_document() by setting the template parameter. This overrides any custom settings you have in your YAML metadata, ensuring that all articles are rendered in the same way (and receive the default site template).

If you need to override the output format, or set any options, you'll need to add a pkgdown field to your yaml metadata:

pkgdown:
  as_is: true

This will tell pkgdown to use the output_format (and options) that you have specified. This format must accept template, theme, and self_contained in order to work with pkgdown. If the output needs a theme, you'll have to specify it even if it is "default", and you might experience Bootstrap incompatibilities between the output and pkgdown.

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

pkgdown:
  as_is: true
  extension: pdf

If you want to set an output format for all your articles, you can do that by adding a vignettes/_site.yml, much like you would for an rmarkdown website. For example, you can backport some bookdown features such as cross-references to all your articles by using the bookdown::html_document2 format.

output:
  bookdown::html_document2:
  number_sections: false

Suppressing vignettes

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 build_site() details.

Figures

You can control the default rendering of figures by specifying the figures field in _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 options. other.parameters is a list of parameters that will be available to custom graphics output devices such as HTML widgets.