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