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
vignettes/tutorials are 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.
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 = ".")
Path to package.
An optional named list used to temporarily override
Name of article to render. This should be either a path
Additional data to pass on to template.
You can control the articles index and navbar with a
articles section in
_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
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
contents (required): a list of article names to include in the
section. This can either be names of individual vignettes or a
starts_with(). The name of a vignette includes its
vignettes without extension so that the name of the vignette
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 for 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.
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 with
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
self_contained in order to work with pkgdown.
If the output format produces a PDF, you'll also need to specify the
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
For example, you can backport some bookdown features such as cross-references
to all your articles by using the
output: bookdown::html_document2: number_sections: false
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 TOC depth via the YAML configuration file:
toc: depth: 2
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