This function generates the home page, converts
.md files found in the
package root (and in
.github/), and builds an authors page from
inst/CITATION (if present).
build_home(pkg = ".", override = list(), preview = NA, quiet = TRUE)
Path to package.
An optional named list used to temporarily override
The home page (
index.html) is generated from
README.md, in that order. Most packages will use
because that's also displayed by GitHub and CRAN. Use
index.md if you want
your package website to look different to your README, and use
_pkgdown/index.md if you don't want that file to live in your package
If you use
README.Rmd it's your responsibility to knit
the document to create the corresponding
.md. pkgdown does not do this
for you because it only touches files in the
The sidebar is automatically populated with:
Development status badges found in
identifies badges in three ways:
A link for bug reports is added if the
BugReports field in
DESCRIPTION contains a link. You can use
to populate this field.
Licensing information if
files are present.
Community information is linked in the side bar using the
Extra markdown files in the base directory or in
.github/ are copied
docs/ and converted to HTML.
Citation information from a
inst/CITATION file is linked in the side bar
to the authors page.
Author ORCID identification numbers in the
DESCRIPTION are linked under
"Developers" using the ORCID logo:
If you want to include images in your
README.md, they must be stored
somewhere in the package so that they can be displayed on the CRAN website.
The best place to put them is
man/figures. If you are generating figures
with R Markdown, make sure you set up
fig.path as followed:
knitr::opts_chunk$set( fig.path = "man/figures/" )
This should usually go in a block with
include = FALSE.
If you have a package logo, you can include it at the top of your README in a level-one heading:
# pkgdown <img src="man/figures/logo.png" align="right" />
init_site() will also automatically create a favicon set from your package
To tweak the home page, you need a section called
By default, the page title and description are extracted automatically
single quotes off quoted words). CRAN ensures that these fields don't contain
phrases like "R package" because that's obvious on CRAN. To make your
package more findable with google, it's good practice to override the
description, thinking about what people might search for:
home: title: An R package for pool-noodle discovery description: > Do you love R? Do you love pool-noodles? If so, you might enjoy using this package to automatically discover and add pool-noodles to your growing collection.
(Note the use of YAML's
>; this is a convenient way of writing paragraphs
The sidebar links are automatically generated by inspecting the
BugReports fields of the
DESCRIPTION. You can add additional links with a
links, which should contain a list of
home: links: - text: Link text href: http://website.com
READMEs usually start with an
<h1> containing the package name. If
that feels duplicative with the package name in the navbar you can
remove it with
home: strip_header: true
The "developers" list is populated by the maintainer ("cre"), authors
("aut"), and funder ("fnd") from the
DESCRIPTION. You can modify their
display on the home page by adding a subsection for
authors. Each entry
authors should be named with the author's name (matching
and can contain
href is provided, the author's name will be linked to this url.
html is provided, it will be shown instead of the author's name.
This is particularly useful if you want to display the logo of a corporate
authors: firstname lastname: href: "http://name-website.com" html: "<img src='name-picture.png' height=24>"