Build a complete pkgdown website

build_site() is a convenient wrapper around six functions:

• init_site()

• build_home()

• build_reference()

• build_articles()

• build_tutorials()

• build_news()

See the documentation for the each function to learn how to control that aspect of the site.

Note if names of generated files were changed, you will need to use clean_site() first to clean up orphan files.

build_site(
  pkg = ".",
  examples = TRUE,
  run_dont_run = FALSE,
  seed = 1014,
  lazy = FALSE,
  override = list(),
  preview = NA,
  devel = FALSE,
  new_process = !devel,
  install = !devel,
  document = "DEPRECATED"
)

Arguments

pkg

Path to package.

examples

Run examples?

run_dont_run

Run examples that are surrounded in \dontrun?

seed

Seed used to initialize so that random examples are reproducible.

lazy

If TRUE, will only rebuild articles and reference pages if the source is newer than the destination.

override

An optional named list used to temporarily override values in _pkgdown.yml

preview

If TRUE, or is.na(preview) && interactive(), will preview freshly generated section in browser.

devel

Use development or deployment process?

If TRUE, uses lighter-weight process suitable for rapid iteration; it will run examples and vignettes in the current process, and will load code with pkgload::load_all().

If FALSE, will first install the package to a temporary library, and will run all examples and vignettes in a new process.

build_site() defaults to devel = FALSE so that you get high fidelity outputs when you building the complete site; build_reference(), build_home() and friends default to devel = TRUE so that you can rapidly iterate during development.

new_process

If TRUE, will run build_site() in a separate process. This enhances reproducibility by ensuring nothing that you have loaded in the current process affects the build process.

install

If TRUE, will install the package in a temporary library so it is available for vignettes.

document

Deprecated Use devel instead.

YAML config

There are five top-level YAML settings that affect the entire site: destination, url, title, template, and navbar.

destination controls where the site will be generated. It defaults to docs/ (for GitHub pages), but you can override if desired. Relative paths will be taken relative to the package root.

url optionally specifies the url where the site will be published. Supplying this will:

• Allow other pkgdown sites to link to your site when needed, rather than using generic links to https://rdrr.io. See vignette("linking") for more information.

• Generate a sitemap.xml, increasing the searchability of your site.

• Automatically generate a CNAME when deploying to github.

url: https://pkgdown.r-lib.org

title overrides the default site title, which is the package name. It's used in the page title and default navbar.

You can also provided information to override the default display of the authors. Provided a list named with the name of each author, including href to add a link, or html to override the text:

authors:
  Hadley Wickham:
    href: http://hadley.nz
  RStudio:
    href: https://www.rstudio.com
    html: <img src="https://www.tidyverse.org/rstudio-logo.svg" height="24" />

Development mode

The development mode of a site controls four main things:

• Where the site is built.

• The colour of the package version in the navbar.

• The optional tooltip associated with the version.

• The indexing of the site by search engines.

You can override the default development mode by adding a new development field to _pkgdown.yml, e.g.

development:
  mode: devel

There are currently four possible modes:

• release (mode: release), the default. Site is written to docs/. Version in navbar gets the default colouring.

• development (mode: devel). Site is written to docs/dev/. Version in navbar gets the "danger" class and a message stating these are docs for an in-development version of the package. The noindex meta tag is used to ensure that these packages are not indexed by search engines.

• unreleased (mode: unreleased). Site is written to docs/. Version in navbar gets the "danger" class, and a message indicating the package is not yet on CRAN.

• automatic (mode: auto): pkgdown automatically detects the mode based on the version number:

  • 0.0.0.9000 (0.0.0.*): unreleased.

  • four version components: development.

  • everything else -> release.

There are three other options that you can control:

development:
  destination: dev
  version_label: danger
  version_tooltip: "Custom message here"

destination allows you to override the default subdirectory used for the development site; it defaults to dev/. version_label allows you to override the style used for development (and unreleased) versions of the package. It defaults to "danger", but you can set to "default", "info", or "warning" instead. (The precise colours are determined by your bootstrap theme, but become progressively more eye catching as you go from default to danger). Finally, you can choose to override the default tooltip with version_tooltip.

YAML config - navbar

By default, the top navbar will contain links to:

• "Get Started", if you have an article with the same name as the package (e.g., vignettes/pkgdown.Rmd).

• The reference index.

• Articles (i.e., vignettes, if present).

• News (if present).

• An icon linking to the source repository.

You can override (and even remove) these defaults with the navbar field. It has two primary components: structure and components. These components interact in a somewhat complicated way, but the complexity allows you to make minor tweaks to part of the navbar while relying on pkgdown to automatically generate the rest.

The structure defines the layout of the navbar, i.e. the order of the components, and whether they're right aligned or left aligned. You can use this component to change the order of the default components, remove some default components and add your own components.

navbar:
 structure:
   left:  [intro, reference, articles, tutorials, news]
   right: [github]

The components describes the appearance of each element in the navbar. It uses the same syntax as RMarkdown. The following YAML snippet illustrates some of the most important features.

navbar:
 components:
   articles:
    text: Articles
    menu:
    - text: Category A
    - text: Title A1
      href: articles/a1.html
    - text: Title A2
      href: articles/a2.html
    - text: -------
    - text: "Category B"
    - text: Title B1
      menu:
      - text: "Sub-category B11"
        href: articles/b11.html
    twitter:
      icon: "fab fa-twitter fa-lg"
      href: https://twitter.com/hadleywickham
      aria-label: "twitter account"

Components can contain sub-menus with headings (indicated by missing href) and separators (indicated by a bunch of -). You can also use icons from fontawesome. When using icons with no text, for accessibility it's best practice to include an aria-label for screenreader users.

This yaml would override the default "articles" component, and add a new "twitter" component. Unless you explicitly mention new components in the structure they'll be added to the far right of the left menu.

You can also customize the color scheme of the navbar by using the type and bg parameters:

navbar:
  type: dark
  bg: primary

will produce a navbar with a dark background of the primary color (defined by Bootstrap default, a Bootswatch theme, or bslib variable cf vignette("customization", package ="pkgdown"))

YAML config - search

You can use docsearch by algolia to add search to your site.

template:
  params:
    docsearch:
      api_key: API_KEY
      index_name: INDEX_NAME

You also need to add a url: field, see above.

YAML config - template

You can get complete control over the appearance of the site using the template component. There are two components to the template: the HTML templates used to layout each page, and the css/js assets used to render the page in the browser.

The easiest way to tweak the default style is to use a bootswatch template, by passing on the bootswatch template parameter to the built-in template:

template:
  bootswatch: cerulean

Note that if you use Bootstrap version 3 the syntax is

template:
  params:
    bootswatch: cerulean

Refer to vignette("customization", package = "pkgdown").

Optionally provide the ganalytics template parameter to enable Google Analytics. It should correspond to your tracking id.

When enabling Google Analytics, be aware of the type and amount of user information that you are collecting. You may wish to limit the extent of data collection or to add a privacy disclosure to your site, in keeping with current laws and regulations.

template:
  params:
    ganalytics: UA-000000-01

Suppress indexing of your pages by web robots by setting noindex: true:

template:
  params:
    noindex: true

You can also override the default templates and provide additional assets. You can do so by either storing them in the directories pkgdown/assets and pkgdown/templates, or by supplying path and asset_path pointing to alternative folders. To suppress inclusion of the default assets, set default_assets to false.

template:
  path: path/to/templates
  assets: path/to/assets
  default_assets: false

These settings are currently recommended for advanced users only. There is little documentation, and you'll need to read the existing source for pkgdown templates to ensure that you use the correct components.

For further information including how to provide templates and assets in a separate package, see vignette("customization", package = "pkgdown").

YAML config - repo

pkgdown automatically generates links to the source repository in a few places

• Articles and documentation topics are linked back to the underlying source file.

• The NEWS automatically links issue numbers and user names.

• The homepage provides a link to "Browse source code"

pkgdown automatically figures out the necessary URLs if you link to a GitHub or GitLab repo in your BugReports or URL field. Otherwise, you can supply your own in the repo component:

repo:
  url:
    home: https://github.com/r-lib/pkgdown/
    source: https://github.com/r-lib/pkgdown/blob/master/
    issue: https://github.com/r-lib/pkgdown/issues/
    user: https://github.com/

• home: path to package home on source code repository.

• source:: path to source of individual file in master branch.

• issue: path to individual issue.

• user: path to user.

The varying components (e.g. path, issue number, user name) are pasted on the end of these URLs so they should have trailing /s.

pkgdown can automatically link to Jira issues as well, but you must specify both a custom issue URL as well as your Jira project names to auto-link in jira_projects. You can specify as many projects as you would like in a last (in the example below we would link both the PROJ and OTHER Jira projects):

repo:
  jira_projects: [PROJ, OTHER]
  url:
    issue: https://jira.organisation.com/jira/browse/

pkgdown defaults to using the "master" branch for source file URLs. This can be configured to use a specific branch when linking to source files by specifying a branch name:

repo:
  branch: main

YAML config - deploy

deploy currently offers a single parameter:

• install_metadata allows you to install package index metadata into the package itself. Normally this metadata is made available on the published site; installing it into your package means that it's available for autolinking even if your website is not reachable at build time (e.g. because it's only behind the firewall or requires auth).

  deploy:
    install_metadata: true
  

YAML config - footer

By default, the footer is automatically populated with:

• The names of the authors authors, on the left.

• A reference to pkgdown pkgdown, on the right.

The example below puts the authors information on the right together with a legal disclaimer, and puts pkgdown on the left.

footer:
 left:
   structure: [pkgdown]
 right:
   structure: [authors, legal]
   components:
     legal: Provided without ***any warranty***.

Like the navbar and side, you can control both the structure and the components. Unlike the navbar or sidebar, the components of the footer are just pasted together into a string that converted to HTML and insert in the document.

YAML config - redirects

If you change the structure of your documentation (by renaming vignettes or help topics) you can setup redirects from the old content to the new content. One or several now-absent pages can be redirected to a new page (or to a new section of a new page). This works by creating a html page that performs a "meta refresh", which isn't the best way of doing a redirect but works everywhere that you might deploy your site.

The syntax is the following, with old paths on the left, and new paths or URLs on the right.

redirects:
  - ["articles/old-vignette-name.html", "articles/new-vignette-name.html"]
  - ["articles/another-old-vignette-name.html", "articles/new-vignette-name.html"]
  - ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"]

If for some reason you choose to redirect an existing page make sure to exclude it from the search index, see ?build_search.

Options

Users with limited internet connectivity can disable CRAN checks by setting options(pkgdown.internet = FALSE). This will also disable some features from pkgdown that requires an internet connectivity. However, if it is used to build docs for a package that requires internet connectivity in examples or vignettes, this connection is required as this option won't apply on them.

Users can set a timeout for build_site(new_process = TRUE) with options(pkgdown.timeout = Inf), which is useful to prevent stalled builds from hanging in cron jobs.

Examples

if (FALSE) {
build_site()

build_site(override = list(destination = tempdir()))
}