View source: R/build-articles.R
build_articles | R Documentation |
build_articles()
renders each R Markdown file underneath vignettes/
and
saves it to articles/
. There are two exceptions:
Files that start with _
(e.g., _index.Rmd
) are ignored,
enabling the use of child documents.
Files in vignettes/tutorials
are handled by build_tutorials()
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,
seed = 1014L,
override = list(),
preview = FALSE
)
build_article(
name,
pkg = ".",
lazy = FALSE,
seed = 1014L,
new_process = TRUE,
pandoc_args = character(),
override = list(),
quiet = TRUE
)
build_articles_index(pkg = ".", override = list())
pkg |
Path to package. |
quiet |
Set to |
lazy |
If |
seed |
Seed used to initialize random number generation in order to
make article output reproducible. An integer scalar or |
override |
An optional named list used to temporarily override
values in |
preview |
If |
name |
Name of article to render. This should be either a path
relative to |
new_process |
Build the article in a clean R process? The default,
|
pandoc_args |
Pass additional arguments to pandoc. Used for testing. |
You can control the articles index and navbar with a articles
field in
your _pkgdown.yml
. If you use it, pkgdown will check that all articles
are included, and will error if you have missed any.
The articles
field defines a list of sections, each of which
can contain four fields:
title
(required): title of section, which appears as a heading on the
articles index.
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
navbar.
contents
(required): a list of article names to include in the
section. This can either be names of individual vignettes or a
call to starts_with()
. The name of a vignette includes its
path under vignettes
without extension so that the name of the vignette
found at vignettes/pizza/slice.Rmd
is pizza/slice
.
The title and description of individual vignettes displayed on the index
comes from title
and 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
fields. navbar: ~
means that the "Main verbs"
will appear in the navbar without a heading; the absence of the navbar
field in 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.,
vignettes/pkgdown.Rmd
or vignettes/articles/pkgdown.Rmd
) automatically
becomes a top-level "Get started" link, and will not appear in the articles
drop-down.
(If your package name includes a .
, e.g. pack.down
, use a -
in the
vignette name, e.g. pack-down.Rmd
.)
pkgdown will warn if there are (non-internal) articles that aren't listed
in the articles index. You can suppress such warnings by listing the
affected articles in a section with title: internal
(case sensitive);
this section will not be displayed on the index page.
You can link to arbitrary additional articles by adding an
external-articles
entry to _pkgdown.yml
. It should contain an array
of objects with fields name
, title
, href
, and description
.
external-articles: - name: subsampling title: Subsampling for Class Imbalances description: Improve model performance in imbalanced data sets through undersampling or oversampling. href: https://www.tidymodels.org/learn/models/sub-sampling/
If you've defined a custom articles index, you'll need to include the name
in one of the contents
fields.
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.
By default, pkgdown builds all articles using the
rmarkdown::html_document()
output
format, ignoring whatever is set in
your YAML metadata. This is necessary because pkgdown has to integrate the
HTML/CSS/JS from the vignette with the HTML/CSS/JS from rest of the site.
Because of the challenges of combining two sources of HTML/CSS/JS, there is
limited support for other output formats and you have to opt-in by setting
the as_is
field in your .Rmd
metadata:
pkgdown: as_is: true
If the output format produces a PDF, you'll also need to specify the
extension
field:
pkgdown: as_is: true extension: pdf
To work with pkgdown, the output format must accept template
, theme
, and
self_contained
arguments, and must work without any additional CSS or
JSS files. Note that if you use
_output.yml
or _site.yml
you'll still need to add as_is: true
to each individual vignette.
Additionally, htmlwidgets do not work when as_is: true
.
If you want articles
that are not vignettes, use usethis::use_article()
to create it. 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 figures by specifying the figures
field in _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 other.parameters: []
Most of these parameters are interpreted similarly to knitr chunk
options. other.parameters
is a list of parameters
that will be available to custom graphics output devices such
as HTML widgets.
Other site components:
build_home()
,
build_news()
,
build_reference()
,
build_tutorials()
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.