Automatic reports with Bookdown and GitHub actions

4 min readMay 12, 2022

Sometimes we make plots and graphs with data that is being updated from time to time, like when you are collecting data points during a time course experiment.

In this particular case, you can be interested in setting up a GitHub repository hosting both the collected data and the final reports. GitHub allows you to host a minimum website known as GitHub Pages.

Having a system that triggers the execution of a new report each time you make a modification is what is finally needed to make your automatic reports. This is actually achievable thanks to the GitHub actions.

Imagine that you have a CSV file that is updated each day or week. Having a system that makes a plot reading this file and stores it on the same website will be a nice add-on to your repository.

If you make your plots with R you might be interested in developing a website using Bookdown, an open-source package that allows writing books, websites, and reports with R Markdown.

You can install R, Bookdown, and other libraries using directly the GitHub actions.

Input data

To do so let’s make a new repository and write a small dataset called data.csv.

The data.csv can contain something like:

x,y
0,0
1,1
2,2
3,3

Bookdown files

We then need 4 files for making our bookdown website:

The first one contains information on the bookdown website:

title: "test-bookdown"
author: ".."
date: "`r Sys.Date()`"
book_filename: "test-bookdown"
language:
  ui:
    chapter_name: "Part "
delete_merged_file: true
rmd_files: ["index.Rmd"]
output:
  bookdown::gitbook:
    theme: cosmo
    highlight: tango
output_format: html

such as the title of the website, the kind of output, the number of R markdown files to render etc.

The second is just the theme you want to use and the kind of markdown parser engine (kramdown).

theme: jekyll-theme-dinky
title: test-bookdown
markdown: kramdown
kramdown:
  parse_block_html: true

The third contains information on the kind of output produced. You can also have pdf download of report, some custom link in the main webpage etc.

bookdown::gitbook:
  highlight: pygments
  split_by: section
  config:
    toc:
      collapse: section
      before: |
        <li><a href="./">TEST-Bookdown</a></li>
      after: |
        <li><a href="https://github.com/lucacozzuto/test_bookdown/" target="blank">TEST-Bookdown</a></li>
    download: ["pdf", "epub"]
    search: yes
bookdown::html_book:
  theme: spacelab
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

Finally the last one is the one that will be read and “rendered”, so converted in a static HTML website by bookdown. This is an example:

---
title: "Test-Bookdown"

author:
  - Luca Cozzuto


site: bookdown::test-bookdown
output: bookdown::gitbook
documentclass: book
biblio-style: apalike
link-citations: yes
---


# Welcome
Hi, this is my test bookdown. Here a silly R script:

## A plot
```{r echo=FALSE, warning = FALSE, message=FALSE, fig.width=7}
a<-read.csv("data.csv")
plot(a)
```

As you can see we need to have three ` for adding the R code directly on the R markdown page.

GitHub pages

Now we need to add the GitHub actions for the automatic rendering of the Bookdwon website, the creation of the GitHub page, and the automatic push on a branch that will be displayed as a website. For doing so we need to make a file in a folder structure like this:

.github/workflows/deploy_bookdown.yml

The content has to contain a trigger at the beginning:

on:
  push:
     branches:
     # Default branches below
       - main
       - masterand two actions:

Render-Book, in which we use a number of pre-built GitHub actions for using R and installing the custom libraries like markdown and bookdown.

jobs:  bookdown:
    name: Render-Book
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: r-lib/actions/setup-r@v1
      - uses: r-lib/actions/setup-pandoc@v1
      - name: Install TinyTeX
        uses: r-lib/actions/setup-tinytex@v1
        env:
          TINYTEX_INSTALLER: TinyTeX
      - 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@v2
        with:
          name: _book
          path: _book/

checkout-and-deploy: this will use other pre-built actions for deploying the final pages to an empty branch called gh-pages:

 checkout-and-deploy:
   runs-on: ubuntu-20.04
   needs: bookdown
   steps:
     - name: Checkout
       uses: actions/checkout@v2
     - name: Download artifact
       uses: actions/download-artifact@v2
       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
        branch: gh-pages