R: Set Top-level YAML options for pkgdown

yml_pkgdown {ymlthis}

R Documentation

Set Top-level YAML options for pkgdown

Description

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⁠

Usage

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"
    )
  )