The goal of pkgdown is to make it easy to make an elegant and useful package website with a minimum of work. You can get a basic website up and running in just a couple of minutes:
# Run once to configure package to use pkgdown
usethis::use_pkgdown()
# Run to build the website
pkgdown::build_site()If you’re using GitHub, we also recommend setting up GitHub actions to automatically build and publish your site:
usethis::use_pkgdown_github_pages()While you’ll get a decent website without any additional work, if you
want a website that really pops, you’ll need to read the rest of this
vignette. It starts by showing you how to configure pkgdown with a
_pkgdown.yml. You’ll learn about the main components of the
site (the home page, reference, articles, and news), and then how to
publish and promote your site.
You can override pkgdown’s defaults with a YAML file called
_pkgdown.yml1. The most important field is
url, which gives the final location of the site:
url: https://pkgdown.r-lib.orgurl is used throughout the site to generate absolute
urls where they are needed.
Another important option is template, which allows you
to control the overall appearance of your site:
template:
bootstrap: 5
bootswatch: ceruleanYou can learn more about controlling the appearance of your site in
vignette("customise").
If your documentation (.Rd and .Rmd) is
written in a language other than English, declare it by setting setting
lang to the two letter
language code for your language:
lang: frThis will be used to set the language of the web page and to translate the English words that pkgdown generates on your site. Current available translations are:
de: Germandk: Danishes: Spanishfr: Frenchko: Koreanpt: Portuguesetr: Turkishzh_CN: Chinese (simplified)The contents of home page are automatically generated from
index.md or README.md. pkgdown tries them in
order, so it’s possible to have a different display on GitHub and
pkgdown by providing both files. The homepage also includes a sidebar
full of useful links; see ?build_home for how these are
generated and how you can customise them.
pkgdown creates a function reference in reference/ that
includes one page for each .Rd help topic in
man/. The translation of individual help topics from Rd to
HTML is generally straightforward, but there are a couple of things you
should bear in mind:
pkgdown does its best to autolink all references to help topics
and articles described in vignette("linking").
pkgdown executes all examples, inserting the rendered results in the generated HTML files.
By default, pkgdown generates a reference index that is just an
alphabetically-ordered list of functions. The index is much more useful
with human curation because functions can be grouped and described in
categories. To override the default, provide a reference
field in _pkgdown.yml.
Each entry in reference can take one of three forms:
title and optional
desc (description) fields.subtitle and optional
desc (description) fields.contents field.reference:
- title: "Connecting to Spark"
desc: >
Functions for installing Spark components and managing
connections to Spark
contents:
- spark_config
- spark_connect
- spark_disconnect
- spark_install
- spark_log
- title: "Reading and Writing Data"
desc: "Functions for reading and writing Spark DataFrames."
contents:
- starts_with("spark_read")
- starts_with("spark_write")
- matches("saveload")Note the use of starts_with() to select all functions
with a common prefix. You can also use ends_with() and
matches(). See complete details in
?build_reference.
While iterating on the reference index you might want to run
pkgdown::build_reference_index(). It just re-builds the
index page, making it faster to quickly change _pkgdown.yml
and see how it affects your site.
pkgdown will automatically build all vignettes found in
vignettes/, translating them to HTML files in
articles/. Due to the way that pkgdown has to integrate
RMarkdown generated HTML with its own HTML, relatively little control is
available over the output format. You can see the details in
?build_articles.
If you want to include an article on the website but not in the
package (e.g., because it’s large), you can either place it in a
subdirectory of vignettes/
(e.g. vignettes/web_only) or add it to
.Rbuildignore (and make sure that there’s no
vignettes: section in the yaml header). In the extreme case
where you want to produce only articles but not vignettes, you should
add the complete vignettes/ directory to
.Rbuildignore and ensure that DESCRIPTION does not have a
VignetteBuilder field.
If NEWS.md is present, it will be rendered into a
single-page changelog based on markdown level headings. pkgdown assumes
your NEWS.md is formatted using level one headings
(#) to specify package name and version number, and level
two headings (##) to provide topical organization for each
release.
# pkgdown 1.1.0
## Bug Fixes
* Lots of them
# pkgdown 1.0.0
* This is the first release of pkgdown.See more suggestions for writing news bullets in the tidyverse style guide.
See ?build_news for more customisation options including
how to:
If you use GitHub, there are two ways to publish your site on GitHub Pages:
Build the site locally, check in the docs directory, then configure GitHub Pages to use that directory.
Use GitHub actions to automatically build and publish the site
every time you make a change. The easiest way to set this up is to run
usethis::use_pkgdown_github_pages().
Once your finalized site is built and published on the web, you should publicize its URL in a few places:
The URL field of your package
DESCRIPTION, alongside a link to its source:
URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown(usethis::use_pkgdown_github_pages() does this for
you.)
Your repository description on GitHub.
On Twitter (make sure to include #rstats).
You can also put it in pkgdown/_pkgdown.yml
if you want to keep the package root clutter-free, or in
inst/_pkgdown.yml if you want to make it available when
your package is installed.↩︎