Moving from bookdown to Quarto (and the corresponding GitHub Actions changes)

What I did to keep R4DS-ES simple.

Mauricio “Pachá” Vargas S.


June 6, 2023

R and Shiny Training: If you find this blog to be interesting, please note that I offer personalized and group-based training sessions that may be reserved through Buy me a Coffee. Additionally, I provide training services in the Spanish language and am available to discuss means by which I may contribute to your Shiny project.


Recently, the R for Data Science in Spanish repository (R Para Ciencia de Datos) has shown some errors when users send pull requests (i.e., see the most recent at the time of writing).

A few weeks ago I stopped using Netlify to render the R4DS-ES website, and I went back to GitHub Pages. I explained all the steps in a previous post.

I need to keep the project and contributions as simple as possible, so I moved the book to Quarto.

Renaming files

To rename all the files, I wrote a small bash script in the root of the project:


# rename all Rmd files to qmd
for f in *.Rmd; do
    mv -- "$f" "${f%.Rmd}.qmd"

Then I run it with bash and all the files were renamed from Rmd to qmd.

Installing Quarto

As I explained in a previous post, I created my own APT to be able to run apt install quarto on Linux Mint (i.e., Ubuntu).

Rendering the book locally

From Visual Studio Code, I opened index.qmd and I was able to render the book and see it in the preview pane after doing the following changes:

  1. Rename bookdown.yml to _quarto.yml.
  2. Delete _output.tml.
  3. Delete the header from index.qmd
  4. Downgrade to knitr version 1.42 (i.e., see this bug report about)

On the left side, I could see some entries that read “(PART) Explorar”. To fix this I deleted the headers of the form # (PART) Explorar from QMD files, and modified the _quarto.yml file to list the parts of the book:

  type: book
  output-dir: docs
  title: "R Para Ciencia de Datos"
  date: "2023-06-06"
    - index.qmd
    - 01-intro.qmd
    - part: "Explorar"
      - 02-explore.qmd
      - 03-visualize.qmd
      - 04-workflow-basics.qmd
      - 05-transform.qmd
      - 06-workflow-scripts.qmd
      - 07-eda.qmd
      - 08-workflow-projects.qmd
    - part: "Manejar o domar datos"
      - 09-wrangle.qmd
      - 10-tibble.qmd
      - 11-import.qmd
      - 12-tidy.qmd
      - 13-relational-data.qmd
      - 14-strings.qmd
      - 15-factors.qmd
      - 16-datetimes.qmd
    - part: "Programar"
      - 17-program.qmd
      - 18-pipes.qmd
      - 19-functions.qmd
      - 20-vectors.qmd
      - 21-iteration.qmd
    - part: "Modelar"
      - 22-model.qmd
      - 23-model-basics.qmd
      - 24-model-building.qmd
      - 25-model-many.qmd
    - part: "Comunicar"
      - 26-communicate.qmd
      - 27-rmarkdown.qmd
      - 28-communicate-plots.qmd
      - 29-rmarkdown-formats.qmd
      - 30-rmarkdown-workflow.qmd
    theme: cosmo

In order to process changes on the fly, I added a file _metadata.yml with the following content:

# freeze computational output
# (see
freeze: auto

Rendering the book on GitHub Actions

Because R4DS-ES used a peer review process, I had to create the infrastructure to render the book on GitHub Actions. This is because it kept things simple, and the website could be updated when I merged a pull request.

I modified the file .github/workflows/render-book.yml to the following:

    branches: traduccion

name: Render and Publish

    runs-on: ubuntu-latest
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Setup R
        uses: r-lib/actions/setup-r@v2

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

      - name: Get R version
        id: get-r-version
        run: echo "version=$(Rscript -e 'cat(as.character(getRversion()))')" >> $GITHUB_OUTPUT
        shell: bash  

      - name: Cache R packages
        uses: actions/cache@v3
          path: ${{ env.R_LIBS_USER }}
          key: ${{ runner.os }}-${{ steps.get-r-version.outputs.version }}-3-

      - name: Install pak
        run: |
          install.packages("pak", repos = "")
        shell: Rscript {0}

      - name: Install dependencies
        run: |
        shell: Rscript {0}

      - name: Install knitr 1.42 to avoid bug in 1.43
        run: |
          devtools::install_version("knitr", version = "1.42")
        shell: Rscript {0}

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
          tinytex: false
      - name: Publish to GitHub Pages (and render)
        uses: quarto-dev/quarto-actions/publish@v2
          target: gh-pages
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions

Note the line that downgrades knitr to version 1.42 for the reasons explained above. The file is adapted from Quarto Actions.

Optional steps

Because I moved a bit from the configurations of the original book, I renamed the metapackage r4ds we use to install the book’s dependencies to r4dses and I did some spring cleaning in the DESCRIPTION, .Rbuildignore, and I removed some files that were not needed anymore. The result was to obtain zero errors, warnings, and notes when running devtools::check().

It is important to mention that the book repository is, in part an R package, and the command devtools::install_github("cienciadedatos/r4ds") shall install the book’s dependencies by reading the DESCRIPTION file on it.

Book’s repository

The main changes consisted in moving everything, adding rmarkdown as a dependency, and downgrading knitr.

You can see the final result here.