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. This page documents options that affect the whole site.
Usage
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
, oris.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 withpkgload::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 todevel = FALSE
so that you get high fidelity outputs when you building the complete site;build_reference()
,build_home()
and friends default todevel = TRUE
so that you can rapidly iterate during development.- new_process
If
TRUE
, will runbuild_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.
General config
destination
controls where the site will be generated, defaulting todocs/
. Paths are relative to the package root.url
is optional, but strongly recommended.url: https://pkgdown.r-lib.org
It specifies where the site will be published and is used to allow other pkgdown sites to link to your site when needed (
vignette("linking")
), generate asitemap.xml
, automatically generate aCNAME
when deploying to github, generate the metadata needed rich social "media cards" (vignette("metadata")
), and more.title
overrides the default site title, which is the package name. It's used in the page title and default navbar.
Development mode
The development
field allows you to generate different sites for the
development and released versions of your package. To use it, you first
need to set the development mode
:
development:
mode: auto
Setting development mode
The development mode
of a site controls where the site is built,
the colour of the package version in the navbar, the version tooltip,
and whether or not the site is indexed by search engines. There are
four possible modes:
automatic (
mode: auto
): automatically determines the mode based on the version number:0.0.0.9000
(0.0.0.*
): unreleased.four version components: development.
everything else -> release.
release (
mode: release
), the default. Site is written todocs/
. Version in navbar gets the default colouring. Development badges are not shown in the sidebar (see?build_home
).development (
mode: devel
). Site is written todocs/dev/
. The navbar version gets a "danger" class and a tooltip stating these are docs for an in-development version of the package. Thenoindex
meta tag is used to ensure that these packages are not indexed by search engines. Development badges are shown in the sidebar (see?build_home
).unreleased (
mode: unreleased
). Site is written todocs/
. Version in navbar gets the "danger" class, and a message indicating the package is not yet on CRAN. Development badges are shown in the sidebar (see?build_home
).
You can override the mode specified in the _pkgdown.yml
by setting
by setting PKGDOWN_DEV_MODE
to devel
or release
.
Selective HTML
You can selectively show HTML only on the devel or release site by adding
class pkgdown-devel
or pkgdown-release
. This is most easily accessed
from .Rmd
files where you can use pandoc's <div>
syntax to control
where a block of markdown will display. For example, you can use the
following markdown in your README to only show GitHub install instructions
on the development version of your site:
::: {.pkgdown-devel}
You can install the development version of pkgdown from GitHub with:`remotes::install_github("r-lib/pkgdown")`
:::
You can use a similar technique to control where badges are displayed. This markdown show the CRAN status badge on the site for the released package and the GitHub check status for the development package:
[![CRAN Status](https://www.r-pkg.org/badges/version/pkgdown)]
(https://cran.r-project.org/package=pkgdown){.pkgdown-release}[![R-CMD-check](https://github.com/r-lib/pkgdown/workflows/R-CMD-check/badge.svg)]
(https://github.com/r-lib/pkgdown/actions){.pkgdown-devel}
Other options
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
.
Navigation bar
You can customise the navigation bar that appears at the top of the page with the navbar
field.
It's made up of two pieces: structure
, which defines the overall layout, and components
, which defines what each piece looks like.
This organisation makes it easy to mix and match pkgdown defaults with your own customisations.
This is the default structure:
navbar:
structure:
left: [intro, reference, articles, tutorials, news]
right: [search, github]
It makes use of the the six built-in components:
intro
: "Get Started", which links to a vignette with the same name as the package.reference
, if there are any.Rd
files.articles
, if there are any vignettes or articles.tutorials
, if there any tutorials.news
, ifNEWS.md
exists.search
, the search box (seevignette("search")
for more details).github
, a link to the source repository (with an icon), if it can be automatically determined from theDESCRIPTION
.
You can use the structure
field to reorganise the navbar without changing the default contents:
navbar:
structure:
left: [search]
right: [reference, articles]
You can use components
to override the default content.
For example, this yaml provides a custom articles menu:
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: Article B1
href: articles/b1.html
Components uses the same syntax as RMarkdown menus.
The elements of menu
can be:
A link (
text
+href
)A heading (just
text
)A separator (
text: ——–
)
Instead of text, you can also use the name of an icon
s from fontawesome.
You should also provide a textual description in the aria-label
field for screenreader users.
To add a new component to the navbar, you need to modify both structure
and components
.
For example, the following yaml adds a new "twitter" component that appears to the left of the github icon.
navbar:
structure:
right: [twitter, github]
components:
twitter:
icon: fa-twitter
href: http://twitter.com/hadleywickham
aria-label: Twitter
Finally, you can add arbitrary HTML to three locations in the navbar:
template:
includes:
before_title: <!-- inserted before the package title in the header ->
before_navbar: <!-- inserted before the navbar links -->
after_navbar: <!-- inserted after the navbar links -->
These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down.
You can also customise the colour scheme of the navbar by using the type
and bg
parameters. See vignette("customise")
for more details.
Footer
You can customise the footer with the footer
field.
It's made up of two pieces: structure
, which defines the overall layout, and components
, which defines what each piece looks like.
This organisation makes it easy to mix and match the pkgdown defaults with your own customisations.
This is the default structure:
footer:
structure:
left: developed_by
right: built_with
Which uses two of the three built-in components:
developed_by
, a sentence describing the main authors of the package. (See?build_home
if you want to tweak which authors appear in the footer.)built_with
, a sentence advertising pkgdown.package
, the name of the package.
You can override these defaults with the footer
field.
The example below puts the authors' information on the right along with a legal disclaimer, and puts the pkgdown link on the left.
footer:
structure:
left: pkgdown
right: [authors, legal]
components:
legal: Provided without **any warranty**.
Each side is pasted into a single string (separated by " "
) and then converted from markdown to HTML.
Search
The search
field controls the built-in search. See vignette("search")
for details.
Template
The template
field is mostly used to control the appearance of the site.
See vignette("customise")
for details.
There are two other template
fields that control other aspects of the
site:
noindex: true
will suppress indexing of your pages by search engines:template: params: noindex: true
google_site_verification
allows you to verify your site with google:template: params: google_site_verification: _nn6ile-a6x6lctOW
trailing_slash_redirect: true
will automatically redirectyour-package-url.com
toyour-package-url.com/
, using a JS script added to the<head>
of the home page. This is useful in certain redirect scenarios.template: trailing_slash_redirect: true
Analytics
To capture usage of your site with a web analytics platform, you can make
use of the includes
field to add the HTML supplied to you by the platform.
Typically these are either placed after_body
or in_header
. I include
a few examples below, but I highly recommend getting the recommended HTML
directly from the platform.
-
template: includes: after_body: > <script data-goatcounter="https://{YOUR CODE}.goatcounter.com/count" data-goatcounter-settings="{YOUR SETTINGS}" async src="https://gc.zgo.at/count.js"></script>
-
template: includes: in_header: | <!-- Global site tag (gtag.js) - Google Analytics --> <script async src="https://www.googletagmanager.com/gtag/js?id={YOUR TRACKING ID}"#' ></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', '{YOUR TRACKING ID}'); </script>
-
templates: includes: in_header: | <script defer data-domain="{YOUR DOMAIN}" src="https://plausible.io/js/plausible.js"></script>
Source repository
Use the repo
field to override pkgdown's automatically discovery
of your source repository. This is used in the navbar, on the homepage,
in articles and reference topics, and in the changelog (to link to issue
numbers and user names). pkgdown can automatically figure 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
field:
repo:
url:
home: https://github.com/r-lib/pkgdown/
source: https://github.com/r-lib/pkgdown/blob/HEAD/
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 default 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 if specify both a
custom issue
URL as well Jira project names to auto-link in
jira_projects
. You can specify as many projects as you would like:
repo:
jira_projects: [this_project, another_project]
url:
issue: https://jira.organisation.com/jira/browse/
pkgdown defaults to using the "HEAD" 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: devel
Deployment (deploy
)
There is a single deploy
field
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 behind a firewall or requires auth).deploy: install_metadata: true
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.