How to generate a great website and reference manual for your R package
Tags: r, githubactions, jekyll
Published: 2024-04-10 08:52:15

---
title: How to generate a great website and reference manual for your R package
published: True
description: A GitHub action that mixes Jekyll and pkgdown
tags: R, githubactions, jekyll
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2c31f7bsfcp6tvzqlo9x.png
# published_at: 2024-04-10 08:50 +0000
---

Generating a website for your [R](https://r-project.org) 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](https://cran.r-project.org/package=dupNodes). I found [`pkgdown`](https://pkgdown.r-lib.org/), 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](https://jj.github.io/r-dupNodes), 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

```yaml
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:

```yaml
      - 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:

```yaml
      - 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:

```yaml
      - 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](https://jj.github.io/R-dupNodes). A website with reference and articles, updated automatically, without having to wait for CRAN updates!