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