How to generate a great website and reference manual for your R package

Generating a website for your R package is always a great idea. If the package is based on some paper, it will help it get noticed and eventually used. And once you have a website, it's just as well to include a reference manual for the package in it, that complements or is a bit more updated than the one published in CRAN. Or simply in another format.

That's what I tried to do for my package dupNodes. I found pkgdown, an one-stop solution for generating websites, which even generates the GitHub action for you.

I had a problem, though. I already had some semblance of website, using Jekyll to generate the pages from markdown, and just plain HTML elsewhere, for presentations and other stuff. And pkgdown generated an index.html, overwriting at least the main stuff, and not including some images I had in the README.md file.

So I decided to combine both in the same workflow. Here's what I had initially

name: Deploy Jekyll with GitHub Pages dependencies preinstalled

on:
  push:
    branches: ["master"]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site

This is the default GitHub action generated by GitHub itself, pretty vanilla stuff. What it says is that it generates the HTML stuff to be deployed in a subdirectory called _site.

So far so good. The only thing you have to do is to tell pkgdown to generate it stuff in the same directory (or subdirectory thereof), right?

Wrong. jekyll-build-pages uses a docker container for generating the image, and that one does not follow the best practice of using a non-privileged user. Everything generated in _site has root privileges, so pkgdown failed with an EACCESS error.

So I had to add this step after that:

      - name: Change permissions built site
        run: sudo chown -R runner _site

Simple enough, but required some research to check who was the user running the GitHub action. After that, it was easy to incorporate the rest of the GitHub action, copypasta from the one generated by pkgdown itself:

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

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

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::pkgdown, local::.
          needs: website

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

The only change over the original is the dest_dir right above this: it's generated to _site/docs, within the _site directory that will be packaged for deployment.

Just one thing left. pkgdown does not seem to be aware of images linked from the README.md when it generates the cover for the site. So these had to be added too:

      - name: Link images
        run: cp -r _site/img _site/docs/

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

Initial version used symbolic links, but upload-pages-artifact choked on it, so I had to physically copy the directory.

And that's it now. A website with reference and articles, updated automatically, without having to wait for CRAN updates!