build_site() is a convenient wrapper around six functions:
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" )
Path to package.
Run examples that are surrounded in \dontrun?
Seed used to initialize so that random examples are reproducible.
An optional named list used to temporarily override
Use development or deployment process?
There are five top-level YAML settings that affect the entire site:
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:
sitemap.xml, increasing the searchability of your site.
Automatically generate a
deploying to github.
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,
href to add a link, or
html to override the
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" />
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.
There are currently three possible development modes:
release: site written to
docs/, the version gets the default
colouring, and no message.
development: written to
docs/dev/, the version gets a danger label,
and message stating these are docs for an in-development version of the
noindex meta tag is used to ensure that these packages are
not indexed by search engines.
unreleased: the package is written to
docs/, the version gets a "danger"
label, and the message indicates the package is not yet on CRAN.
The default development mode is "release". You can override it by adding a
development field to
development: mode: devel
You can also have pkgdown automatically detect the mode with:
development: mode: auto
The mode will be automatically determined based on the version number:
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
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
By default, the top navigation bar (the "navbar") will contain links to:
The home page, with a "home" icon.
"Get Started", if you have an article with the same name as the package
Articles (i.e., vignettes, if present).
News (if present).
A "github" icon with a link to your
github repo (if listed in the
DESCRIPTION url field).
You can override these defaults with the
navbar field. It has two primary
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.
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,
and to add your own components.
navbar: structure: left: [home, intro, reference, articles, tutorials, news] right: [github]
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: home: ~ 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
This yaml would override the default "articles" component, eliminate
the "home" 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 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.
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: params: bootswatch: cerulean
See a complete list of themes and preview how they look at https://gallery.shinyapps.io/117-shinythemes/:
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
template: params: noindex: true
You can also override the default templates and provide additional
assets. You can do so by either storing in a
or by supplying
asset_path. To suppress inclusion
of the default assets, set
default_assets to false.
template: package: mycustompackage # OR: 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.
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
URL field. Otherwise, you can
supply your own in the
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
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
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
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.