pkgdown (version 1.4.1)

build_articles: Build articles section

Description

Each R Markdown vignette in vignettes/ and its subdirectories is rendered and saved to articles/.

The only exception are .Rmd vignettes that start with _ (i.e., _index.Rmd), enabling the use of child documents in bookdown, and vignettes in a tutorials subdirectory, which is reserved for tutorials built with build_tutorials()

Vignettes are rendered using a special document format that reconciles rmarkdown::html_document() with your pkgdown template.

Note that when run by itself (i.e. not by build_site()), vignettes will use a previous installed version of the package, not the current source version.

Usage

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.

Get started vignette

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". Rmarkdown files in vignettes/tutorials/ are ignored, because these are assumed to contain tutorials, see build_tutorials().

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 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() 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 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