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)
Path to package.
Set to FALSE to display output of knitr and
pandoc. This is useful when debugging.
If 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 _pkgdown.yml
If TRUE, or 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 index or README.
Additional data to pass on to template.
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 the default is a strong assumption of rmarkdown.
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 aribrary 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.
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
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.
You can control the default rendering of figues 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