22 pkgdown

Published

2025-04-22

TLDR

The pkgdown package helps us easily create websites to enhance the visibility and usability of our app-package through a professional and informative website.

Install pkgdown
Run usethis::use_pkgdown_github_pages() to set up the package and writes the configuration file (_pkgdown.yml)
Customize _pkgdown.yml as needed, then
Run pkgdown::build_site_github_pages() to build your site
Push the changes to deploy it online for others to access!

In this chapter, we’ll cover setting up a pkgdown website for our app-package. Building a package website isn’t required, but it’s a great way to confirm your package is documented and structured correctly, and it gives you an opportunity to share all of your hard work! pkgdown can be configured to automatically generate a beautiful website from a pre-specified Git branch GitHub Actions.

Accessing the code examples

I’ve created the shinypak R package In an effort to make each section accessible and easy to follow:

Install shinypak using pak (or remotes):

# install.packages('pak')
pak::pak('mjfrigaard/shinypak')

Review the chapters in each section:

library(shinypak)
list_apps(regex = 'pkgdown')
## # A tibble: 1 × 2
##   branch     last_updated       
##   <chr>      <dttm>             
## 1 22_pkgdown 2025-03-13 06:20:26

Launch an app:

launch(app = "22_pkgdown")

A pkgdown website makes our Shiny app and its accompanying package more accessible to potential users by providing them with a central location for any information they need (app features, updates, etc.).

22.1 Setting up `pkgdown`

The magic of pkgdown is it’s conversion of an existing R package structure into a website with documentation for our application.

install.packages("pkgdown")

pkgdown has a usethis function similar to testthat for setup:¹

usethis::use_pkgdown_github_pages()

use_pkgdown_github_pages() takes care of (most of) the setup for our app-package website, but we’ll break down the steps below.²

22.1.1 `_pkgdown.yml`

The initial output after running use_pkgdown_github_pages() looks something like the following:

use_pkgdown_github_pages() output

I’ve replaced my GitHub username with <UserName> and the name of the app-package/repository with <pkgName>

✔ Setting active project to '/Users/<UserName>/projects/<pkgName>'
✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
✔ Adding 'docs' to '.gitignore'
✔ Writing '_pkgdown.yml'
• Modify '_pkgdown.yml'
✔ Recording 'https://<UserName>.github.io/<pkgName>/' as site's url in '_pkgdown.yml'
✔ Adding 'https://<UserName>.github.io/<pkgName>/' to URL
✔ Setting 'https://<UserName>.github.io/<pkgName>/' as homepage of GitHub repo '<UserName>/<pkgName>'

_pkgdown.yml is initially created with only the url, template, and bootstrap version:

url: https://<UserName>.github.io/<pkgName>/
template:
  bootstrap: 5

These fields are all that’s required to launch your pkgdown site, but in the following sections we’ll cover how to edit _pkgdown.yml to customize the fonts, colors, contents, and layout of our site.

22.1.2 `gh-pages` branch

use_pkgdown_github_pages() sets up publishing our app-package site from an ‘orphan branch from GitHub pages’:

✔ Initializing empty, orphan 'gh-pages' branch in GitHub repo '<UserName>/<pkgName>'
✔ GitHub Pages is publishing from:
• URL: 'https://<UserName>.github.io/<pkgName>/'
• Branch: 'gh-pages'

Orphan branches

An orphan branch is a new Git branch with no commit history, effectively starting a new ‘root’ in our project’s development history. For our app-package, the gh-pages branch serves as a new line of development, completely separated from all other branches.

We’re also told GitHub pages will be publishing our app-package website at the following URL: https://<UserName>.github.io/<pkgName>/

22.1.3 `.github/workflows/`

use_pkgdown_github_pages() creates a GitHub Action workflow folder (.github/workflows/) with a YAML file (pkgdown.yaml):

• Path: "/"
✔ Adding "*.html" to .github/.gitignore.
✔ Saving "r-lib/actions/examples/pkgdown.yaml@v2" to .github/workflows/pkgdown.yaml.
☐ Learn more at <https://github.com/r-lib/actions/blob/v2/examples/README.md>.

We’re also told the contents in this file are copied from the r-lib/actions repository (which we’ve covered previously in Section 21.1 and Section 21.2).

22.2 Building site

usethis has two functions for building your pkgdown site:

build_site()
build_site_github_pages()

We used use_pkgdown_github_pages() to configure our app-package, so we’ll use build_site_github_pages() to build our site.

pkgdown::build_site_github_pages()

In the following sections, we’ll take a look at how the files and folders in our app-package are used to create the site’s contents. As mentioned above, the great thing about pkgdown sites is that they use our existing package structure to build a beautiful site that’s easy to navigate (with minimal changes).

22.2.1 `docs/`

The docs/ folder contains the .html files for our website (that’s why ^docs$ was added to the .Rbuildignore and docs was added to the .gitignore). After creating a home for our site contents, the site initialization files are copied from the local pkgdown installation into docs/

== Building pkgdown site ======================================================
Reading from: '/Users/<UserName>/<pkgName>'
Writing to:   '/Users/<UserName>/<pkgName>/docs'

22.2.2 `README.md` -> `index.html`

The landing page (index.html) for our app-package website is built from the README.md file. An example of the site URL is below:

https://<UserName>.github.io/<pkgName>/index.html

The <UserName> is our GitHub username, and the <pkgName> is the name of our package. The authors.html is built from the Author and Maintainer fields in the DESCRIPTION file. Long-form documentation can be stored in vignettes (Section 1.15.3) which will be converted into articles (covered below).

Standard README for your app-package

If you’d like a boilerplate README.md for an R package, you can use usethis::use_readme_rmd():

usethis::use_readme_rmd()

✔ Setting active project to '/Users/<UserName>/projects/<pkgName>'
✔ Writing 'README.Rmd'
✔ Adding '^README\.Rmd$' to '.Rbuildignore'
• Modify 'README.Rmd'
✔ Writing '.git/hooks/pre-commit'

At minimum, the README.Rmd should include:

The purpose/goal of your app-package
Instructions for installation
Links to a deployed version (if applicable)
Supporting packages

If I chose to use this README.md file, I usually remove the .git/hooks/pre-commit (so they don’t interfere with my personal add/commit/push process).

unlink('.git/hooks/pre-commit')

22.2.3 `man/` -> Reference

The functions documented in the man/ folder are converted into individual items in the Reference menu item (see Chapter 5). I’ve included two examples below:

man/
  ├── display_type.Rd
  └── launch_app.Rd

── Building function reference ───────────
Writing reference/index.html
Reading man/display_type.Rd
Writing reference/display_type.html
Reading man/launch_app.Rd
Writing reference/launch_app.html

Functions will only be included in the Reference if they’ve been exported (see Section 6.1)
The @seealso and @family tags will create hyperlinks between our utility functions, modules, UI/server/standalone app functions (see Section 5.2)
All @examples will be run and displayed (Section 5.1.6)

22.2.4 `vignettes` -> Articles

The .Rmd files in the vignettes folder are rendered as HTML files and displayed under an Articles menu item. The exception to this is any vignettes with the same name as our app-package. This vignette will automatically be listed under a menu dropdown titled “Get Started”:³

vignettes/
  ├── sap.Rmd
  └── specs.Rmd

-- Building articles -------------
Writing 'articles/index.html'
Reading 'vignettes/sap.Rmd'
Writing 'articles/sap.html'
Reading 'vignettes/specs.Rmd'
Writing 'articles/specs.html'
== DONE ==========================

The final step in the build process is to add a .nojekyll file in the repository (this hidden file is necessary for pkgdown sites configured to deploy from GitHub pages).

-- Extra files for GitHub pages ----------------------------------------------
Writing '.nojekyll'

22.3 Customize layout

We can customize the look of our pkgdown site by editing the contents of _pkgdown.yml.

22.3.1 Themes, colors and fonts

Below are some examples of the fields that control the bootswatch theme (<THEME>), code syntax highlighting(<HIGHLIGHTING>):

YAML Fields

template:
  bootstrap: 5
  bootswatch: <THEME>
  theme: <HIGHLIGHTING>

In `_pkgdown.yml`

template:
  bootstrap: 5
  bootswatch: united
  theme: atom-one-light

We can use the bslib package for additional control over the fonts and colors on our site. The <COLOR> should be replaced with a color hex, and <FONT> can include any freely available Google fonts.⁴

YAML Fields

  bslib:
    primary: "<COLOR>"
    code-color: "<COLOR>"
    code-bg: "<COLOR>"
    base_font:
      google: <FONT>
    heading_font:
      google: <FONT>
    code_font:
      google: <FONT>

In `_pkgdown.yml`

  bslib:
    primary: "#02577A"
    code-color: "#007bff"
    code-bg: "#EAE9EA"
    base_font:
      google: Ubuntu
    heading_font:
      google: Fira Sans Condensed
    code_font:
      google: Ubuntu Mono

You can see the theme, color, and font choices below:

pkgdown template in yml — pkgdown `template` in yml

22.3.2 Articles

The articles should include a link to the landing page for our app, and provide detailed examples of how it works, including links to any additional resources or documentation.

The navbar components can also be customized with titles, sections, and article names. In _pkgdown.yml, the articles are listed under components, and we will add a text title (Docs) and sub-heading (Specs):

In `_pkgdown.yml`

navbar:
 components:
   articles:
    text: Docs
    menu:
    - text: "Specs"

Output

As noted above, any vignette with a filename that matches the package name will be automatically named ‘Getting Started’ in the navbar. We can also add sections with article titles by placing them in text fields. These are listed under the menu (note the indentation), with a path to the html file.

I’ve listed the App Specifications vignette under a "Specs" section (see Chapter 15), and linked to articles/specs.html:

In `_pkgdown.yml`

    text: Docs
    menu:
    - text: "Specs"
    - text: App Specifications
      href: articles/specs.html

Output

Use ------- with a text field to create horizontal separators between sections (without a corresponding href).

I’ve added a Modules section and a Application Modules vignette (stored in vignettes/modules.Rmd and published to articles/modules.html):

In `_pkgdown.yml`

    text: Docs
    menu:
    - text: "Specs"
    - text: App Specifications
      href: articles/specs.html
    - text: -------
    - text: "Modules"
    - text: App Modules
      href: articles/modules.html

Output

22.3.3 Function reference

pkgdown will automatically generate a Package index section for any object with an .Rd file in the man/ folder. This includes functions we’ve explicitly exported with (i.e., with @export) and functions we’ve documented with @keywords internal.⁵

By default, the function are sorted alphabetically, but we can customize them into sections with titles and descriptions using the fields below in _pkgdown.yml:

reference:
- title: "<TITLE>"
  desc: >
    <DESCRIPTION>
  contents:
  - <FUNCTION>

For example, we can include a section for the modules we’re exporting from our app-package:

In `_pkgdown.yml`

reference:
- title: "Modules"
  desc: >
    App modules

Output

Customizing Reference

The _pkgdown.yml file must include all exported functions if you customize the reference field. If not, you’ll see an error when you try to build your site:

-- Building function reference ------------------------------------
Error in `check_missing_topics()`:
! All topics must be included in reference index
✖ Missing topics: <FUN>
ℹ Either add to _pkgdown.yml or use @keywords internal

To help organize and display the functions in your app-package, we can use tidyselect helpers⁶ in the bullets below contents.

For example, we can list modules with starts_with("mod"):⁷

In `_pkgdown.yml`

reference:
- title: "Modules"
  desc: >
    Application modules
  contents:
  - starts_with("mod")

Output

We can also use _pkgdown.yml to list any datasets we’ve documented (see Section 7.3) in our app-package.

In `_pkgdown.yml`

- title: "Data"
  desc: "App data"
  contents:
  - movies

Output

22.4 Deploying your site

The .github/workflows/pkgdown.yaml file automates building and deploying our app-package’s pkgdown site. This workflow file is configured to be triggered by a specific GitHub event, build the website using the standard R package files, then deploys the site to GitHub Pages. Below we’ll breakdown the fields and values of the workflow (and their functions):

22.4.1 Event

1. Set to trigger on push to the 22_pkgdown branch

on:
  push:
    branches: [22_pkgdown]

a. Also triggers when a release is published, allowing the website to showcase the latest version of the package.⁸

  release:
    types: [published]

b. workflow_dispatch allows the workflow to be manually triggered from the GitHub Actions web interface (for ad-hoc updates).⁹

  workflow_dispatch:

22.4.2 Jobs

2. name defines a single job with the ID pkgdown.

name: pkgdown

22.4.3 Runner

3. The pkgdown job ID runs on the latest Ubuntu runner provided by GitHub Actions.

jobs:
  pkgdown:
    runs-on: ubuntu-latest

4. The comment Only restrict concurrency for non-PR jobs refers to the concurrency field,¹⁰ which prevents concurrent runs of the job for non-pull request events (avoiding conflicts or redundant deployments). group¹¹ uses a dynamic expression to differentiate between pull_request events and github.event_name, using the run ID (github.run_id) for pull requests to allow concurrency.

    # Only restrict concurrency for non-PR jobs
    concurrency:
      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}

22.4.4 Map

5. env maps the GITHUB_PAT environment variable using the GitHub token, secrets.GITHUB_TOKEN (which allows the workflow to authenticate and perform operations within the repository).

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

6. permissions explicitly grants the workflow write permissions to the repository, enabling it to push changes (like an updated website).

    permissions:
      contents: write

22.4.5 Steps

7. Checks out the repository’s code, making it available to subsequent steps.

  steps:
    - uses: actions/checkout@v4

8. Installs pandoc, which is necessary for rendering markdown documents and vignettes.

    - uses: r-lib/actions/setup-pandoc@v2

9. Sets up the R environment and configures it to use the public RStudio package manager (use-public-rspm) for faster package installations.

    - uses: r-lib/actions/setup-r@v2
      with:
        use-public-rspm: true

10. Installs the dependencies required by our app-package and pkgdown.

    - uses: r-lib/actions/setup-r-dependencies@v2

a. Specifies installing any::thing from pkgdown and the local:: package (our app-package).¹²

      with:
        extra-packages: any::pkgdown, local::.
        needs: website

11. Executes pkgdown::build_site_github_pages() within an R script shell to build the pkgdown website. It’s configured not to start a new R process for the build and not to install our app-package (assuming dependencies are already handled in step 10).

    - name: Build site
      run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
      shell: Rscript {0}

12. Uses JamesIves/github-pages-deploy-action@v4.5.0 to deploy the site to GitHub Pages (provided the event is not a pull request).

    - name: Deploy to GitHub pages 🚀
      if: github.event_name != 'pull_request'
      uses: JamesIves/github-pages-deploy-action@v4.5.0

a. Specifies not to clean the deployment branch, deploys it to the gh-pages branch, and sets the site content source folder to docs

      with:
        clean: false
        branch: gh-pages
        folder: docs

.github/workflows/pkgdown.yaml performs more operations than the previous workflows. However, these extra steps allow us to use the gh-pages branch to maintain and showcase up-to-date package documentation for users, contributors, and collaborators. When we’re happy with the layout of our website in _pkgdown.yml, we can add, commit, and push the changes back to the repo:

git add .
git commit -m "updates to _pkgdown.yml"
git push

22.5 GitHub

After pushing the changes to the 22_pkgdown branch, we can see our new 22_pkgdown workflow listed with the previous 21.1_gha-style (Section 21.1) and 21.2_gha-shiny-deploy (Section 21.2) workflows in the Actions tab:

Launch app with the shinypak package:

launch('22_pkgdown')

The pkgdown sites can take a few minutes to build, but we can monitor it’s progress from the Actions tab:

Workflow created on push to 22_pkgdown branch — Workflow created on `push` to `22_pkgdown` branch

The workflow file triggers the following steps:

Back in the Actions tab, we see a new pages build and deployment workflow has been created with a ‘bot’ tag:

The updates to _pkgdown.yml workflow represents the changes we committed and pushed to the 22_pkgdown branch (#21), but we configured our website to be served from the gh-pages branch (#22). Each time we push changes to 22_pkgdown and trigger the pkgdown workflow, a corresponding pages build and deployment workflow will be triggered to build and deploy the site:

Build and deploy pkgdown site — Build and deploy `pkgdown` site

This automated deployment process is essential for maintaining up-to-date documentation or website content for R packages (like sap) without manual intervention, making it easier for developers to focus on development while ensuring that users always have access to the latest information.

View the package website here.

Recap

pkgdown is handy for creating beautiful, functional websites for your app-package. Package sites help share your app-package with others in a more engaging and informative way.

Recap:

Installation
```
install.packages('pkgdown)`
```
Setup: create a configuration file that pkgdown will use to build your site with one of the usethis functions below:
```
usethis::use_pkgdown_github_pages()
# or
# usethis::use_pkgdown() 
```
- These create a _pkgdown.yml configuration file that lets us customize how our site looks and which parts of our app-package are diplayed/highlighted.
Customize: we can change our pkgdown site theme, set colors and fonts, organize the navigation bar, and add custom sections and pages. For an app-package, this means we can create a landing page for our Shiny app, provide detailed articles on how it works, and link to any additional resources or documentation.

Building Your Site

pkgdown::build_site_github_pages()
# or 
# pkgdown::build_site()

build_site_github_pages() goes through our app-package (function documentation, and examples, RMarkdown vignettes, README, NEWS, etc.) and assembles a coherent, navigable site.
Deploying Your Site: after building a pkgdown site, we can use GitHub Actions to upload the generated website contents to GitHub Pages, which hosts our app-package site directly from a GitHub repository.

usethis also has a generic function for using pkgdown (use_pkgdown()), but we’re going to cover building and deploying our app-package site using GitHub pages. Read more about use_pkgdown() in the usethis documentation.↩︎
Internally, this function calls usethis::use_pkgdown(), usethis::use_github_pages(), and usethis::use_github_action("pkgdown"). Read more in the usethis documentation.↩︎
I created this vignette with usethis::use_vignette("sap") and included instructions for launching the various apps in sap.↩︎
Read more about bslib in pkgdown sites in the documentation.↩︎
Functions with @keywords internal aren’t listed in the package index, but can be accessed with pkg:::fun() (like the test_logger() function in sap).↩︎
Read more about how to build the function reference here ↩︎
Using the mod_ as a prefix for module functions is a habit I’ve adopted from the golem package (specifically, the add_module() function).↩︎
“You can create releases to bundle and deliver iterations of a project to users.”↩︎
“To enable a workflow to be triggered manually, you need to configure the workflow_dispatch event.”↩︎
“Use concurrency to ensure that only a single job or workflow using the same concurrency group will run at a time.”↩︎
“Concurrency groups provide a way to manage and limit the execution of workflow runs or jobs that share the same concurrency key.”↩︎
The needs: website fields might be a placeholder? I’m unaware of the needs keyword applied within a with clause for setting up dependencies. This also could be intended as a comment or note for future adjustments…↩︎

22.1 Setting up pkgdown

22.1.1 _pkgdown.yml

22.1.2 gh-pages branch

22.1.3 .github/workflows/

22.2 Building site

22.2.1 docs/

22.2.2 README.md -> index.html

22.2.3 man/ -> Reference

22.2.4 vignettes -> Articles

22.3 Customize layout

22.3.1 Themes, colors and fonts

YAML Fields

In _pkgdown.yml

YAML Fields

In _pkgdown.yml

22.3.2 Articles

In _pkgdown.yml

Output

In _pkgdown.yml

Output

In _pkgdown.yml

Output

22.3.3 Function reference

In _pkgdown.yml

Output

In _pkgdown.yml

Output

In _pkgdown.yml

Output

22.4 Deploying your site

22.4.1 Event

22.4.2 Jobs

22.4.3 Runner

22.4.4 Map

22.4.5 Steps

22.5 GitHub

Recap

22.1 Setting up `pkgdown`

22.1.1 `_pkgdown.yml`

22.1.2 `gh-pages` branch

22.1.3 `.github/workflows/`

22.2.1 `docs/`

22.2.2 `README.md` -> `index.html`

22.2.3 `man/` -> Reference

22.2.4 `vignettes` -> Articles

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`

In `_pkgdown.yml`