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:
While you’ll get a decent website without any additional work, if you want a website that really pops, you’ll need read the rest of this vignette. It works through the main components of a pkgdown website:
You can override pkgdown’s defaults with a YAML file called
_pkgdown.yml1. Options that affect the entire site are documented in
build_site() and include:
bootswatch theme that affects the overall appearance of the whole site.
A Google analytics user ID if you want to track the people who are using your site
Customize metadata used for social media cards, as described in
Package search, as described in
The contents of home page is automatically generated from
README.md. pkgdown tries them in order, so if you want a different display for GitHub and pkgdown, you can provide 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
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
reference should be an array of three types objects:
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
matches(). See complete details in
While working on the reference index you might want to run
build_reference_index() instead of
build_site(); that will considerably reduce your iteration time.
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.
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/ 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
More details can be found in
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.
See more suggestions for writing news bullets in the tidyverse style guide.
?build_news for more customisation options including how to:
The easiest way to publish your website is to use GitHub
docs/ directory support. If you want to build and publish your package automatically with GitHub actions, try
Once your finalized site is built and published on the web, you should publicize its URL in a few places:
URL field of your package
DESCRIPTION, alongside a link to its source:
URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown
Your repository description on GitHub.
On Twitter (make sure to include
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.↩︎