Each R Markdown vignette in vignettes/ and its subdirectories is rendered and saved to articles/. Vignettes are rendered using a special document format that reconciles rmarkdown::html_document() with your pkgdown template.

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

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

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.

Details

A vignette with the same name as the package (e.g., vignettes/pkgdown.Rmd) gets special treatment. It is rendered and linked to in the navbar under "Get started".

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.

YAML config

To tweak the index page, you need a section called articles, which provides a list of sections containing, a title, list of contents, and optional description.

For example, this imaginary file describes some of the structure of the R markdown articles:

articles:
- title: R Markdown
  contents:
  - starts_with("authoring")
- title: Websites
  contents:
  - rmarkdown_websites
  - rmarkdown_site_generators

Note that contents can contain either a list of vignette names (including subdirectories), or if the functions in a section share a common prefix or suffix, you can use starts_with("prefix") and ends_with("suffix") to select them all. If you don't care about position within the string, use contains("word"). For more complex naming schemes you can use an arbitrary regular expression with matches("regexp").

pkgdown will check that all vignettes are included in the index this page, and will generate a warning if you have missed any.

YAML header

By default, pkgdown builds all articles with rmarkdown::html_document() using setting the template parameter to a custom built template that matches the site template. You can override this with a pkgdown field in your yaml metadata:

pkgdown:
  as_is: true

This will tell pkgdown to use the output_format that you have specified. This format must accept template, theme, and self_contained in order to work with pkgdown.

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

pkgdown:
  as_is: true
  extension: pdf

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.

Vignette files prefixed with an underscore (e.g., _index.Rmd) are ignored to enable rendering of bookdown sites.

Tables of contents

You can control the TOC depth via the YAML configuration file:

toc:
  depth: 2

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: grDevices::png
  dpi: 96
  dev.args: []
  fig.ext: png
  fig.width: 7.2916667
  fig.height: ~
  fig.retina: 2
  fig.asp: 1.618