Chapter 3 Websites using pkgdown, bookdown, and blogdown

3.1 Create gh-pages branch

In order to serve html pages through GitHub pages the following needs to be done to create an emtpy gh-pages branch to be used to deploy the html pages created by either pkgdown, bookdown, or blogdown

Derived from: https://pkgdown.r-lib.org/reference/deploy_site_github.html

First, we need to create an empty gh-pages branch. In bash:

git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m 'Initial gh-pages commit'
git push origin gh-pages
git checkout master

3.2 Action to deploy a pkgdown site

To add auto-generating website documentation for a package, we can leverage off pkgdown and add it to an existing package, and then use a GitHub action to auto generate the documentation and deploy it to a GitHub pages site.

First, we add the use of pkgdown to the package:

usethis::use_pkgdown()

Then, we want to add in the github action for pkgdown to automatically add documentation. There is an existing yaml template example in the actions package:

usethis::use_github_action(url = "https://raw.githubusercontent.com/r-lib/actions/master/examples/pkgdown.yaml")

The yaml file should be located in .github/workflows/pkgdown.yml and looks like:

on:
  push:
    branches: master

name: Pkgdown

jobs:
  pkgdown:
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@master
      - uses: r-lib/actions/setup-r@master
      - uses: r-lib/actions/setup-pandoc@master
      - name: Install dependencies
        run: |
          Rscript -e 'install.packages("remotes")' \
                  -e 'remotes::install_deps(dependencies = TRUE)' \
                  -e 'remotes::install_github("jimhester/pkgdown@github-actions-deploy")'
      - name: Install package
        run: R CMD INSTALL .
      - name: Deploy package
        run: |
          Rscript -e "pkgdown:::deploy_local(new_process = FALSE, remote_url = 'https://x-access-token:${{secrets.GH_TOKEN}}@github.com/${{github.repository}}.git')"

Now we need to git add and commit the yaml file, and push the changes to GitHub.

3.3 Action to deploy a bookdown site

The following yaml template will run bookdown::render_book() on index.Rmd and then deploy the resulting html files onto the gh-pages branch that was created as part of section 3.1. It also requires the creation of two GitHub secrets (see section 4.2), GH_PAT and EMAIL. GH_PAT is a personal access token that has at least repository access (which means you can see the settings of the repository). Create the token in your personal settings and then copy the value into the secrets settings for the repository (see section 4.2.1 for more). The action also assumes that you are compiling the book to an html format and the output directory is _book.

Github action for .github/workflow/deploy_bookdown.yml

on:
  push:
     branches:
       - master


name: renderbook

jobs:
  bookdown:
    name: Render-Book
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v1
      - uses: r-lib/actions/setup-r@v1
      - uses: r-lib/actions/setup-pandoc@v1
      - name: Install rmarkdown
        run: Rscript -e 'install.packages(c("rmarkdown","bookdown"))'
      - name: Render Book
        run: Rscript -e 'bookdown::render_book("index.Rmd")'
      - uses: actions/upload-artifact@v1
        with:
          name: _book
          path: _book/
  
# Need to first create an empty gh-pages branch
# see https://pkgdown.r-lib.org/reference/deploy_site_github.html
# and also add secrets for a GH_PAT and EMAIL to the repository
# gh-action from Cecilapp/GitHub-Pages-deploy
  checkout-and-deploy:
   runs-on: ubuntu-latest
   needs: bookdown
   steps:
     - name: Checkout
       uses: actions/checkout@master
     - name: Download artifact
       uses: actions/download-artifact@v1.0.0
       with:
         # Artifact name
         name: _book # optional
         # Destination path
         path: _book # optional
     - name: Deploy to GitHub Pages
       uses: Cecilapp/GitHub-Pages-deploy@master
       env:
          EMAIL: ${{ secrets.EMAIL }}               # must be a verified email
          GH_TOKEN: ${{ secrets.GH_PAT }} # https://github.com/settings/tokens
          BUILD_DIR: _book/                     # "_site/" by default
    

This action is performed using two jobs, the first renders html, and the second deploys the html to the gh-pages branch so that it can be viewed using the url <user/org_name>.github.io/<repository_name>. It achieves this by passing an artifact (the _book directory) between jobs. Further information about the action yaml files can be found in chapter 4.

To use the above yaml file that is responsible for deploying this book, you can add it to your book using usethis

usethis::use_github_action(url = "https://raw.githubusercontent.com/ropenscilabs/actions_sandbox/master/.github/workflows/deploy_bookdown.yml")

3.4 Action to deploy a blogdown site

The github action to deploy a blogdown site is very similar to that of the bookdown action in section 3.3 but runs blogdown::build_site(). There are additional configuration steps beyond using the github action to get the site to be correctly deployed - this is because blogdown uses Hugo and github pages uses Jekyll. It also requires the creation of two GitHub secrets (see section 4.2), GH_PAT and EMAIL. GH_PAT is a personal access token that has at least repository access (which means you can see the settings of the repository). Create the token in your personal settings and then copy the value into the secrets settings for the repository (see section 4.2.1 for more).

On an existing blogdown project with git, make sure to add and commit the content you have created, except for public/*. Change the base url in config.toml to baseurl = "/<repo name>/". Create the empty file public/.nojekyll and add and commit it. This tells github not to use Jekyll when displaying your pages. Follow the steps to create an orphaned gh-pages branch in Section 3.1.

Github action for .github/workflow/deploy_blogdown.yml

on:
  push:
     branches:
       - master

name: deployblog

jobs:
  blogdown:
    name: Render-Blog
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v1
      - uses: r-lib/actions/setup-r@v1
      - uses: r-lib/actions/setup-pandoc@v1
      - name: Install rmarkdown
        run: Rscript -e 'install.packages(c("rmarkdown","blogdown"))'
      - name: install hugo
        run: Rscript -e 'blogdown::install_hugo()'
      - name: Render blog
        run: Rscript -e 'blogdown::build_site()'
      - uses: actions/upload-artifact@v1
        with:
          name: public
          path: public/

# Need to first create an empty gh-pages branch
# see https://pkgdown.r-lib.org/reference/deploy_site_github.html
# and also add secrets for a GH_PAT and EMAIL to the repository
# gh-action from Cecilapp/GitHub-Pages-deploy
  checkout-and-deploy:
   runs-on: ubuntu-latest
   needs: blogdown
   steps:
     - name: Checkout
       uses: actions/checkout@master
     - name: Download artifact
       uses: actions/download-artifact@v1.0.0
       with:
         # Artifact name
         name: public # optional
         # Destination path
         path: public # optional
     - name: Deploy to GitHub Pages
       uses: Cecilapp/GitHub-Pages-deploy@master
       env:
          EMAIL: ${{ secrets.EMAIL }}               # must be a verified email
          GH_TOKEN: ${{ secrets.GH_PAT }} # https://github.com/settings/tokens
          BUILD_DIR: public/                     # "_site/" by default

This action will build your blogdown site and then add, commit, and push the resultant files in public/ onto your gh-pages branch where they will be viewable at the url <user/org_name>.github.io/<repository_name>.

To use the above yaml file in your blogdown blog you can add it using usethis

usethis::use_github_action(url = "https://raw.githubusercontent.com/ropenscilabs/actions_sandbox/master/.github/workflows/deploy_blogdown.yml")