Set Top-level YAML options for pkgdown

These functions set YAML for various pkgdown options to be used in _pkgdown.yml. The options are described in greater depth in the pkgdown vignette and in the help pages for pkgdown::build_site(), pkgdown::build_articles(), pkgdown::build_reference(), and pkgdown::build_tutorials(). Essentially, they control the build of vignettes and function references. pkgdown also uses the same approach to navbars as R Markdown. yml_navbar() and friends will help you write the YAML for that. A useful approach to writing pkgdown YAML might be to use pkgdown_template() to build a template based on your package directory, modify with yml_pkgdown_*() and pkgdown_*() functions or yml_replace() and yml_discard(), then pass the results to use_pkgdown_yml() to write to _pkgdown.yml

yml_pkgdown(.yml, as_is = yml_blank(), extension = yml_blank())

yml_pkgdown_opts(
  .yml,
  site_title = yml_blank(),
  destination = yml_blank(),
  url = yml_blank(),
  toc_depth = yml_blank()
)

yml_pkgdown_development(
  .yml,
  mode = yml_blank(),
  dev_destination = yml_blank(),
  version_label = yml_blank(),
  version_tooltip = yml_blank()
)

yml_pkgdown_template(
  .yml,
  bootswatch = yml_blank(),
  ganalytics = yml_blank(),
  noindex = yml_blank(),
  package = yml_blank(),
  path = yml_blank(),
  assets = yml_blank(),
  default_assets = yml_blank()
)

yml_pkgdown_reference(.yml, ...)

pkgdown_ref(
  title = yml_blank(),
  desc = yml_blank(),
  contents = yml_blank(),
  exclude = yml_blank(),
  ...
)

yml_pkgdown_news(.yml, one_page = yml_blank())

yml_pkgdown_articles(.yml, ...)

pkgdown_article(
  title = yml_blank(),
  desc = yml_blank(),
  contents = yml_blank(),
  exclude = yml_blank(),
  ...
)

yml_pkgdown_tutorial(.yml, ...)

pkgdown_tutorial(
  name = yml_blank(),
  title = yml_blank(),
  tutorial_url = yml_blank(),
  source = yml_blank(),
  ...
)

yml_pkgdown_figures(
  .yml,
  dev = yml_blank(),
  dpi = yml_blank(),
  dev.args = yml_blank(),
  fig.ext = yml_blank(),
  fig.width = yml_blank(),
  fig.height = yml_blank(),
  fig.retina = yml_blank(),
  fig.asp = yml_blank(),
  ...
)

yml_pkgdown_docsearch(
  .yml,
  api_key = yml_blank(),
  index_name = yml_blank(),
  doc_url = yml_blank()
)

Arguments

.yml	a `yml` object created by `yml()`, `as_yml()`, or returned by a `yml_*()` function
as_is	Logical. Use the `output_format` and options that you have specified?
extension	The output extension, e.g. "pdf".
site_title	The title of the website (by default, this is the package name). Note that the actual YAML is `title` (specified as `site_title` to avoid duplication with content titles).
destination	The path where the site should be rendered ("docs/" by default)
url	URL where the site will be published; setting the URL will allow other pkgdown sites to link to your site when needed, generate a `sitemap.xml` to increase the searchability of your site, and generate a `CNAME`.
toc_depth	The depth of the headers included in the Table of Contents. Note that the actual YAML is `depth` and is nested under `toc`.
mode	The development mode of the site, one of: "auto", "release", "development", or "unreleased". `development` controls where the site is built; the color of the package version; the optional tooltip associated with the version; and the indexing of the site by search engines. See `?pkgdown::build_site()` for more details.
dev_destination	The subdirectory used for the development site, which defaults to "dev/". Note that the actual YAML is `destination` and is nested under `development`.
version_label	Label to display for "development" and "unreleased" mode. One of: "danger" (the default), "default", "info", or "warning".
version_tooltip	A custom message to include in the version tooltip
bootswatch	A bootswatch theme for the site. See the options at https://rstudio.github.io/shinythemes/.
ganalytics	A Google Analytics tracking id
noindex	Logical. Suppress indexing of your pages by web robots?
package	an R package with with directories `inst/pkgdown/assets` and `inst/pkgdown/templates` to override the default templates and add additional assets; alternatively, you can specify this in `path` and `assets`
path	A path to templates with which to override the default pkgdown templates
assets	A path to additional assets to include
default_assets	Logical. Include default assets?
...	additional named R objects, such as characters or lists, to transform into YAML
title	The title of the article, reference, tutorial, or other resource
desc	A description of the article or reference
contents	The contents, which can also be dplyr-style tidy selectors (e.g `"contains('index')"`).
exclude	What to exclude of the what's captured by `contents`
one_page	Logical. Create one page per release for `NEWS.md`?
name	The name of the file
tutorial_url	The tutorial URL to embed in an iframe
source	A URL to the source code of the tutorial
dev	The graphics device (default: "grDevices::png")
dpi	The DPI (default: 96)
dev.args	A vector of arguments to pass to `dev`
fig.ext	The figure extension (default: "png")
fig.width	The figure width (default: 7.2916667)
fig.height	The figure height (default: `NULL`)
fig.retina	The figure retina value (default: 2)
fig.asp	The aspect ratio (default: 1.618)
api_key	The API key provided by docsearch (see the pkgdown vignette)
index_name	The index name provided by docsearch (see the pkgdown vignette)
doc_url	the URL specifying the location of your documentation. Note that the actual YAML field is `url` but is nested.

Value

a yml object

Examples


yml_empty() %>%
  yml_pkgdown(
    as_is = TRUE,
    extension = "pdf"
  ) %>%
  yml_pkgdown_reference(
    pkgdown_ref(
      title = "pkgdown functions",
      contents = "contains('function_name')"
    )
  ) %>%
  yml_pkgdown_articles(
    pkgdown_article(
      title = "Introduction to the package"
    )
  )
#> ---
#> pkgdown:
#>   as_is: true
#>   extension: pdf
#> references:
#>   title: pkgdown functions
#>   contents: contains('function_name')
#> articles:
#>   title: Introduction to the package
#> ---
#>

Arguments

Value

See also

Examples