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 master3.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:
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 uses two GitHub secrets (see section 4.2): secrets.EMAIL and secrets.GITHUB_TOKEN. Create the token EMAIL in your personal settings and then copy the value into the secrets settings for the repository. GITHUB_TOKEN is used from Cecilapp v3. GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. It is an access token that has repository access (which means you can see the settings of the repository). To learn more about its permissions and examples see Github docs About the GITHUB_TOKEN secret. Furthermore, 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@v3
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
build_dir: _book/ # "_site/" by default
email: ${{ secrets.EMAIL }} # must be a verified email
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
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@v3
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
build_dir: public/ # "_site/" by default
email: ${{ secrets.EMAIL }} # must be a verified email 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