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

See also

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 #> --- #>