Permalink
Cannot retrieve contributors at this time
--- | |
title: "Introduction to pkgdown" | |
description: > | |
Learn how to get started with the basics of pkgdown. | |
output: rmarkdown::html_vignette | |
vignette: > | |
%\VignetteIndexEntry{Introduction to pkgdown} | |
%\VignetteEngine{knitr::rmarkdown} | |
%\VignetteEncoding{UTF-8} | |
--- | |
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: | |
```{r, eval = FALSE} | |
# Run once to configure package to use pkgdown | |
usethis::use_pkgdown() | |
# Run to build the website | |
pkgdown::build_site() | |
``` | |
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 works through the main components of a pkgdown website: | |
1. Metadata | |
1. Home page | |
1. Function reference | |
1. Articles | |
1. News | |
## Metadata | |
You can override pkgdown's defaults with a YAML file called `_pkgdown.yml`[^other-locations]. Options that affect the entire site are documented in `build_site()` and include: | |
* A [`bootswatch`](https://bootswatch.com) theme that affects the overall | |
appearance of the whole site. | |
```yaml | |
template: | |
params: | |
bootswatch: cerulean | |
``` | |
* A Google analytics user ID if you want to track the people who are using your | |
site | |
```yaml | |
template: | |
params: | |
ganalytics: UA-000000-01 | |
``` | |
* A Google site verification code to be added to page headers | |
```yaml | |
template: | |
params: | |
google_site_verification: _nn6ile-a6x6lctOW | |
``` | |
* Customize metadata used for social media cards, as described in | |
`vignette("metadata")`. | |
* Package search, as described in `vignette("search")`. | |
[^other-locations]: 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. | |
## Home page | |
The contents of home page is automatically generated from `index.md` or `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. | |
## Reference | |
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`. The `reference` should be an array of three types objects: | |
* A title, defined by `title` and optional `desc` (description) fields. | |
* A subtitle, defined by `subtitle` and optional `desc` (description) fields. | |
* A list of topics defined by a `contents` field. | |
```yaml | |
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 working on the reference index you might want to run `build_reference_index()` instead of `build_site()`; that will considerably reduce your iteration time. | |
## Articles | |
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 `VignetteBuilder` field. | |
More details can be found in `?build_articles`. | |
## News | |
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. | |
```markdown | |
# 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](https://style.tidyverse.org/news.html). | |
See `?build_news` for more customisation options including how to: | |
* Create one page for each major version and related minor versions. | |
* Add release announcements to the news navbar drop-down. | |
## Publishing | |
The easiest way to publish your website is to use GitHub [`docs/` directory][docs] support. If you want to build and publish your package automatically with GitHub actions, try `usethis::use_github_action("pkgdown")`. | |
## Promoting | |
Once your finalized site is built and published on the web, you should publicize its URL in a few places: | |
1. 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 | |
``` | |
1. Your repository description on GitHub. | |
1. On Twitter (make sure to include `#rstats`). | |
[docs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch |