% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build.R
\name{build_site}
\alias{build_site}
\title{Build a complete pkgdown website}
\usage{
build_site(
  pkg = ".",
  examples = TRUE,
  run_dont_run = FALSE,
  seed = 1014L,
  lazy = FALSE,
  override = list(),
  preview = NA,
  devel = FALSE,
  new_process = !devel,
  install = !devel,
  quiet = TRUE
)
}
\arguments{
\item{pkg}{Path to package.}

\item{examples}{Run examples?}

\item{run_dont_run}{Run examples that are surrounded in \\dontrun?}

\item{seed}{Seed used to initialize random number generation in order to
make article output reproducible. An integer scalar or \code{NULL} for no seed.}

\item{lazy}{If \code{TRUE}, will only rebuild articles and reference pages
if the source is newer than the destination.}

\item{override}{An optional named list used to temporarily override
values in \verb{_pkgdown.yml}}

\item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview
freshly generated section in browser.}

\item{devel}{Use development or deployment process?

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

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

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

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

\item{install}{If \code{TRUE}, will install the package in a temporary library
so it is available for vignettes.}

\item{quiet}{If \code{FALSE}, generate build messages for build functions that
take \code{quiet} arguments.}
}
\description{
\code{build_site()} is a convenient wrapper around six functions:
\itemize{
\item \code{\link[=init_site]{init_site()}}
\item \code{\link[=build_home]{build_home()}}
\item \code{\link[=build_reference]{build_reference()}}
\item \code{\link[=build_articles]{build_articles()}}
\item \code{\link[=build_tutorials]{build_tutorials()}}
\item \code{\link[=build_news]{build_news()}}
\item \code{\link[=build_redirects]{build_redirects()}}
\item \code{\link[=build_llm_docs]{build_llm_docs()}}
}

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.
}
\section{General config}{
\itemize{
\item \code{destination} controls where the site will be generated, defaulting to
\verb{docs/}. Paths are relative to the package root.
\item \code{url} is optional, but strongly recommended.

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{url: https://pkgdown.r-lib.org
}\if{html}{\out{</div>}}

It specifies where the site will be published and is used to allow other
pkgdown sites to link to your site when needed (\code{vignette("linking")}),
generate a \code{sitemap.xml}, automatically generate a \code{CNAME} when
\link[=build_site_github_pages]{deploying to github}, generate the metadata needed
rich social "media cards" (\code{vignette("metadata")}), and more.
\item \code{title} overrides the default site title, which is the package name.
It's used in the page title and default navbar.
}
}

\section{Navbar and footer}{
The \code{navbar} and \code{footer} fields control the appearance of the navbar
footer which appear on every page. Learn more about these fields in
\code{vignette("customise")}.
}

\section{Development mode}{
The \code{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 \code{mode}:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{development:
  mode: auto
}\if{html}{\out{</div>}}
\subsection{Setting development mode}{

The development \code{mode} of a site controls where the built site is placed
and how it is styled (i.e. 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:
\itemize{
\item \strong{automatic} (\code{mode: auto}): determines the mode based on the version:
\itemize{
\item \verb{0.0.0.9000} (\verb{0.0.0.*}): unreleased.
\item four version components: development.
\item everything else -> release.
}
\item \strong{release} (\code{mode: release}), the default. Site is written to \verb{docs/}
and styled like a released package, even if the content is for an
unreleased or development version. Version in navbar gets the default
colouring. Development badges are not shown in the sidebar
(see \code{?build_home}).
\item \strong{development} (\code{mode: devel}). Site is written to \verb{docs/dev/}.
The navbar version gets a "danger" class and a tooltip stating these are
docs for an in-development version of the package. The \code{noindex} meta tag
is used to ensure that these packages are not indexed by search engines.
Development badges are shown in the sidebar (see \code{?build_home}).
\item \strong{unreleased} (\code{mode: unreleased}). Site is written to \verb{docs/}.
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 \code{?build_home}).
}

Use \code{mode: auto} if you want both a released and a dev site, and
\code{mode: release} if you just want a single site. It is very rare that you
will need either devel or unreleased modes.

You can override the mode specified in the \verb{_pkgdown.yml} by setting
by setting \code{PKGDOWN_DEV_MODE} to \code{devel} or \code{release}.
}

\subsection{Selective HTML}{

You can selectively show HTML only on the devel or release site by adding
class \code{pkgdown-devel} or \code{pkgdown-release}. This is most easily accessed
from \code{.Rmd} files where you can use pandoc's \verb{<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:

\if{html}{\out{<div class="sourceCode md">}}\preformatted{::: \{.pkgdown-devel\}
You can install the development version of pkgdown from GitHub with:
`remotes::install_github("r-lib/pkgdown")`
:::
}\if{html}{\out{</div>}}

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:

\if{html}{\out{<div class="sourceCode md">}}\preformatted{[![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\}
}\if{html}{\out{</div>}}
}

\subsection{Other options}{

There are three other options that you can control:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{development:
  destination: dev
  version_label: danger
  version_tooltip: "Custom message here"
}\if{html}{\out{</div>}}

\code{destination} allows you to override the default subdirectory used for the
development site; it defaults to \verb{dev/}. \code{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
\code{version_tooltip}.
}
}

\section{Template}{
The \code{template} field is mostly used to control the appearance of the site.
See \code{vignette("customise")} for details. But it's also used to control
\subsection{Other aspects}{

There are a few other \code{template} fields that control other aspects of the
site:
\itemize{
\item \code{noindex: true} will suppress indexing of your pages by search engines:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{template:
  params:
    noindex: true
}\if{html}{\out{</div>}}
\item \code{google_site_verification} allows you to verify your site with google:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{template:
  params:
    google_site_verification: _nn6ile-a6x6lctOW
}\if{html}{\out{</div>}}
\item \code{trailing_slash_redirect: true} will automatically redirect
\code{your-package-url.com} to \verb{your-package-url.com/}, using a JS script
added to the \verb{<head>} of the home page. This is useful in certain
redirect scenarios.

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{template:
  trailing_slash_redirect: true
}\if{html}{\out{</div>}}
}
}

\subsection{Analytics}{

To capture usage of your site with a web analytics tool, you can make
use of the \code{includes} field to add the special HTML they need. This HTML
is typically placed \code{in_header} (actually in the \verb{<head>}), \code{before_body},
or \code{after_body}.
You can learn more about how includes work in pkgdown at
\url{https://pkgdown.r-lib.org/articles/customise.html#additional-html-and-files}.

I include a few examples of popular analytics platforms below, but we
recommend getting the HTML directly from the tool:
\itemize{
\item \href{https://plausible.io}{plausible.io}:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{template:
  includes:
    in_header: |
      <script defer data-domain="\{YOUR DOMAIN\}" src="https://plausible.io/js/plausible.js"></script>
}\if{html}{\out{</div>}}
\item \href{https://analytics.google.com/analytics/web/}{Google analytics}:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{template:
  includes:
    in_header: |
       <!-- Global site tag (gtag.js) - Google Analytics -->
       <script async src="https://www.googletagmanager.com/gtag/js?id=\{YOUR MEASUREMENT ID\}" ></script>
       <script>
         window.dataLayer = window.dataLayer || [];
         function gtag()\{dataLayer.push(arguments);\}
         gtag('js', new Date());

         gtag('config', '\{YOUR MEASUREMENT ID\}');
       </script>
       <!-- Google tag (gtag.js) -->
}\if{html}{\out{</div>}}
\item \href{https://www.goatcounter.com}{GoatCounter}:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{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>
}\if{html}{\out{</div>}}
}
}
}

\section{Source repository}{
Use the \code{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, GitLab or Codeberg repo in your \code{BugReports}
or \code{URL} field.

Otherwise, you can supply your own in the \code{repo} field:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{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/
}\if{html}{\out{</div>}}
\itemize{
\item \code{home}: path to package home on source code repository.
\item \code{source}: path to source of individual file in default branch
(more on that below).
\item \code{issue}: path to individual issue.
\item \code{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 \code{/}s.

When creating the link to a package source, we have to link to a specific
branch. The default behaviour is to use current branch when in GitHub
actions and \code{HEAD} otherwise. You can overide this default with
\code{repo.branch}:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{repo:
  branch: devel
}\if{html}{\out{</div>}}

pkgdown can automatically link to Jira issues as well if specify both a
custom \code{issue} URL as well Jira project names to auto-link in
\code{jira_projects}. You can specify as many projects as you would like:

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{repo:
  jira_projects: [this_project, another_project]
  url:
    issue: https://jira.organisation.com/jira/browse/
}\if{html}{\out{</div>}}
}

\section{Deployment (\code{deploy})}{
There is a single \code{deploy} field
\itemize{
\item \code{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).

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{deploy:
  install_metadata: true
}\if{html}{\out{</div>}}
}
}

\examples{
\dontrun{
build_site()

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