build_home() function generates pages at the top-level of the site
The home page
HTML files from any
The authors page (from
The citation page (from
inst/CITATION, if present).
The license page
A default 404 page if
.github/404.mdis not found.
build_home_index() rebuilds just the index page; it's useful for rapidly
iterating when experimenting with site styles.
build_home_index(pkg = ".", quiet = TRUE) build_home(pkg = ".", override = list(), preview = NA, quiet = TRUE)
Path to package.
FALSEto display output of knitr and pandoc. This is useful when debugging.
An optional named list used to temporarily override values in
is.na(preview) && interactive(), will preview freshly generated section in browser.
The main content of the home page (
index.html) is generated from
README.md, in that order.
Most packages will use
README.md because that's also displayed by GitHub and CRAN.
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 root directory.
If you use
README.Rmd it's your responsibility to knit the document to create the corresponding
pkgdown does not do this for you because it only touches files in the
Extra markdown files in the base directory (e.g.
ROADMAP.md) or in
CODE_OF_CONDUCT.md) are copied by
docs/ and converted to HTML.
The home page also features a sidebar with information extracted from the package. You can tweak it via the configuration file, to help make the home page an as informative as possible landing page.
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
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 chunk with
include = FALSE.
If you have a package logo, you can include it at the top of your README in a level-one heading:
[init_site()] will also automatically create a favicon set from your package logo.
To tweak the home page, you need a section of the configuration file called
By default, the page title and description are extracted automatically from the
DESCRIPTION (stripping 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 on search engines, it's good practice to override the
description, thinking about what people might search for:
(Note the use of YAML's
> i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
pkgdown identifies badges in three ways:
Any image-containing links between
<!-- badges: start -->and
<!-- badges: end -->, as e.g. created by
usethis::use_readme_rmd(). There should always be an empty line after the
<!-- badges: end -->line. If you divide badges into paragraphs, make sure to add an empty line before the
<!-- badges: end -->line.
Any image-containing links within
Within the first paragraph, if it only contains image-containing links.
By default, pkgdown will display author information in three places:
the left part side of the footer,
the author page.
This documentation describes how to customise the overall author display. See
?build_site for details about changing the location of the authors information within the home sidebar and the site footer.
Author ORCID identification numbers in the
DESCRIPTION are linked using the ORCID logo:
If you want to add more details about authors or their involvement with the package, you can use the comment field, which will be rendered on the authors page.
You can tweak a few things via the
authors YAML field:
display of each author in the footer, sidebar and authors page,
which authors (by role) are displayed in the sidebar and footer,
text before authors in the footer,
text before and after authors in the sidebar,
text before and after authors on the authors page.
You can modify how each author's name is displayed
by adding a subsection for
Each entry in
authors should be named
with the author's name (matching
and can contain
hrefis provided, the author's name will be linked to this URL.
htmlis 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 sponsor.
By default, the "developers" list shown in the sidebar and footer is populated by the maintainer ("cre"), authors
("aut"), and funder ("fnd") from the
You could choose other roles for filtering.
With the configuration below:
only the maintainer and funder(s) appear in the footer, after the text "Crafted by",
all authors and contributors appear in the sidebar,
the authors list on the sidebar is preceded and followed by some text,
the authors list on the authors page is preceded and followed by some text.
If you want to filter authors based on something else than their roles,
consider using a custom sidebar/footer component
You can customise the homepage sidebar with the
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:
These are drawn from seven built-in components:
links: automated links generated from
DESCRIPTIONplus manual links from the
license: Licensing information if
LICENCE.mdfiles are present.
community: links to to
citation: link to package citation information. Uses either
inst/CITATIONor, if absent, information from the
authors: selected authors from the
dev: development status badges found in
toc: a table of contents for the README (not shown by default).
You can also add your own components, where
text is markdown text:
Alternatively, you can provide a ready-made sidebar HTML:
Or completely remove it: